pi-crew 0.9.55 → 0.9.57

package/src/state/{event-log.ts → event-log/event-log.ts}

@@ -1,14 +1,14 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { DEFAULT_EVENT_LOG } from "../config/defaults.ts";
-import { errors } from "../errors.ts";
-import { emitFromTeamEvent } from "../ui/run-event-bus.ts";
-import { type IncrementalReadState, readJsonlSince, readJsonlTail } from "../utils/incremental-reader.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-import { redactSecrets } from "../utils/redaction.ts";
-import { sleep, sleepSync } from "../utils/sleep.ts";
-import { atomicWriteFile } from "./atomic-write.ts";
+import { DEFAULT_EVENT_LOG } from "../../config/defaults.ts";
+import { errors } from "../../errors.ts";
+import { emitFromTeamEvent } from "../../ui/run-event-bus.ts";
+import { type IncrementalReadState, readJsonlSince, readJsonlTail } from "../../utils/incremental-reader.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { redactSecrets } from "../../utils/redaction.ts";
+import { sleep, sleepSync } from "../../utils/sleep.ts";
+import { atomicWriteFile } from "../atomic-write.ts";
 import {
 	applyCompactionUnlocked,
 	currentGeneration,
@@ -69,7 +69,25 @@ const MAX_EVENTS_BYTES = 50 * 1024 * 1024;
 
 const sequenceCache = new Map<string, { size: number; mtimeMs: number; seq: number; lastAccessMs: number }>();
 const MAX_SEQUENCE_CACHE_ENTRIES = 256;
-let appendCounter = 0;
+// P0-2: per-eventsPath append counter. Previously a single module-global shared
+// across all runs AND never incremented on the async path, so the async rotation
+// gate (`0 % 100 === 0`) was always true → needsRotation ran on EVERY async append
+// (a full read+parse+rewrite once the log crossed 4 MB). FIFO-bounded to avoid
+// unbounded growth with run count.
+const appendCounters = new Map<string, number>();
+const APPEND_COUNTER_MAX_ENTRIES = 256;
+export function tickAppendCounter(eventsPath: string, inc = 1): boolean {
+	const prev = appendCounters.get(eventsPath) ?? 0;
+	const next = prev + inc;
+	appendCounters.set(eventsPath, next);
+	if (appendCounters.size > APPEND_COUNTER_MAX_ENTRIES) {
+		const oldest = appendCounters.keys().next().value;
+		if (oldest !== undefined) appendCounters.delete(oldest);
+	}
+	// True when a 100-boundary is crossed (matches the old `next % 100 === 0`
+	// semantics for inc=1, and generalizes to batch increments).
+	return Math.floor(next / 100) > Math.floor(prev / 100);
+}
 let overflowCounter = 0;
 
 /** Simple cross-process lock for an eventsPath to prevent JSONL interleave on concurrent append.
@@ -82,7 +100,7 @@ let overflowCounter = 0;
  *  blocks the Node.js event loop for up to 5s. During that time, AbortSignal handlers
  *  cannot fire, SIGTERM handlers are delayed, and the process appears unresponsive to
  *  orchestrator health checks. Known callers include `appendEvent` (sync path),
- *  `flushOneEventLogBuffer`, and `state/mailbox.ts`. Prefer the async alternative
+ *  `flushOneEventLogBuffer`, and `state/coordination/mailbox.ts`. Prefer the async alternative
  *  (`appendEventAsync`) for all new code.
  */
 export function withEventLogLockSync<T>(eventsPath: string, fn: () => T, options?: { timeoutMs?: number; staleMs?: number }): T {
@@ -288,13 +306,16 @@ function nextSequence(eventsPath: string): number {
 	const stored = readStoredSequence(eventsPath);
 	const fileShrunk = cached && stat.size < cached.size;
 	if (stored !== undefined && !fileShrunk) {
-		// EL-1: the sidecar can regress via sync/async interleave —
-		// appendEventAsync reserves a seq, yields during appendFile/fsync, a
-		// concurrent sync appendEvent reserves+persists a higher seq, then the
-		// async path persists its lower seq — regressing the sidecar below the
-		// file's true max. Trusting the regressed sidecar alone would return a
-		// duplicate seq on the next append. Take max with scanSequence so a
-		// regressed sidecar cannot cause duplicate sequence numbers.
+		// Trust the sidecar, but guard against a REGRESSED sidecar (e.g. the
+		// async path persisted a lower seq, rolling the sidecar back below the
+		// file's true max). Take max with a full scan so a regressed sidecar
+		// cannot produce a duplicate sequence number (EL-1 regression guard).
+		// NOTE (ST-12): a full scan here is acceptable because all three append
+		// paths now allocate seqs via reserveSequence/reserveSequenceUnderLock
+		// (ST-5: re-read sidecar under lock + max with in-process counter);
+		// nextSequence is only consulted for seeding/test helpers, NOT on the
+		// production append path. ST-12's perf goal (avoid 4MB scan on first
+		// append) is therefore met by ST-5 at the reserveSequence layer.
 		const fileMax = scanSequence(eventsPath);
 		const safeSeq = Math.max(stored, fileMax);
 		sequenceCache.set(eventsPath, {
@@ -318,7 +339,9 @@ function nextSequence(eventsPath: string): number {
 
 function persistSequence(eventsPath: string, seq: number): void {
 	try {
-		atomicWriteFile(sequencePath(eventsPath), String(seq));
+		// P0-4: the .seq sidecar is disposable (event-reconstructor tolerates an
+		// inconsistent tail); best-effort avoids 2 fsyncs per event append.
+		atomicWriteFile(sequencePath(eventsPath), String(seq), { durability: "best-effort" });
 	} catch (error) {
 		logInternalError("event-log.persist-sequence-file", error, `eventsPath=${eventsPath}`);
 	}
@@ -335,17 +358,26 @@ function persistSequence(eventsPath: string, seq: number): void {
 // sidecar durable for crash recovery across restarts.
 const seqCounters = new Map<string, number>();
 
-/** Atomically reserve the next sequence number for `eventsPath`. */
+/** Atomically reserve the next sequence number for `eventsPath`.
+ *
+ *  ST-5 (v0.9.56): previously this seeded the in-process `seqCounters` counter
+ *  ONCE per process (reading the `.seq` sidecar a single time via
+ *  `nextSequence`) and then served every subsequent call purely from that
+ *  process-local counter. Two processes that both seeded before either had
+ *  persisted ended up sharing the same counter base -> duplicate sequence
+ *  numbers -> `sinceSeq` streaming readers silently dropped the second event.
+ *  The async path was already fixed via `reserveSequenceUnderLock` (which
+ *  re-reads the sidecar every call); the sync (`appendEvent`) and buffered
+ *  (`appendEventBatchInsideLock`) paths were NOT.
+ *
+ *  Now ALL three append paths share one body: re-read the authoritative `.seq`
+ *  sidecar on EVERY call and take `max(sidecar, inProcess)` so a counter that
+ *  lags behind a sidecar advanced by another process can never assign a
+ *  regressed (duplicate) seq. Every call site already holds a cross-process
+ *  file lock (`withEventLogLockSync` for sync/buffered, `withEventLogLockAsync`
+ *  for async), so the sidecar re-read is race-free within each lock class. */
 function reserveSequence(eventsPath: string): number {
-	let last = seqCounters.get(eventsPath);
-	if (last === undefined) {
-		// Seed once from the authoritative source (sidecar / cache / file scan).
-		// nextSequence() returns the NEXT seq to assign, so the last assigned is one less.
-		last = nextSequence(eventsPath) - 1;
-	}
-	const next = last + 1;
-	seqCounters.set(eventsPath, next);
-	return next;
+	return reserveSequenceUnderLock(eventsPath);
 }
 
 /** Keep the in-process counter monotonic w.r.t. an explicitly-provided seq
@@ -501,7 +533,8 @@ async function withEventLogLockAsync<T>(
 			try {
 				await fs.promises.mkdir(lockDir);
 				try {
-					atomicWriteFile(pidFile, String(process.pid));
+					// P0-4: the lock pid file is disposable stale-lock state; best-effort.
+					atomicWriteFile(pidFile, String(process.pid), { durability: "best-effort" });
 				} catch {
 					/* best-effort */
 				}
@@ -724,12 +757,15 @@ export async function appendEventAsync(eventsPath: string, event: AppendTeamEven
 			// Phase 1.5: when worker atomic writer is enabled, append via worker.
 			if (isWorkerAtomicWriterEnabled()) {
 				await appendFileViaWorker(eventsPath, line);
-				// Worker path: fsync via a separate open (worker manages its own fd).
-				const fd = await fs.promises.open(eventsPath, "r+");
-				try {
-					await fd.sync();
-				} finally {
-					await fd.close();
+				// P0-4 (F3a mirror): fsync terminal events only; non-terminal events are
+				// informational and the event-reconstructor tolerates an inconsistent tail.
+				if (isTerminal) {
+					const fd = await fs.promises.open(eventsPath, "r+");
+					try {
+						await fd.sync();
+					} finally {
+						await fd.close();
+					}
 				}
 			} else {
 				// FIND-10: single-fd append+fsync. Opens in append mode, writes,
@@ -740,7 +776,8 @@ export async function appendEventAsync(eventsPath: string, event: AppendTeamEven
 				const fd = await fs.promises.open(eventsPath, "a");
 				try {
 					await fd.appendFile(line, "utf-8");
-					await fd.sync();
+					// P0-4 (F3a mirror): skip the data fsync for non-terminal events.
+					if (isTerminal) await fd.sync();
 					// FIND-10 R1 fix: the cache-optimization fd.stat() must NOT sit in the
 					// seq-durability critical path. If it threw (rare — fd invalidated),
 					// it would skip persistSequence below and reopen the seq-reuse
@@ -764,7 +801,7 @@ export async function appendEventAsync(eventsPath: string, event: AppendTeamEven
 		// FIND-10: track whether compaction happened after the append so the
 		// cache-update stat can safely reuse postAppendStat (file unchanged).
 		let compactedAfterAppend = false;
-		if (appendCounter % 100 === 0 && needsRotation(eventsPath)) {
+		if (tickAppendCounter(eventsPath) && needsRotation(eventsPath)) {
 			compactedAfterAppend = true;
 			try {
 				const prepared = prepareCompaction(eventsPath);
@@ -865,6 +902,8 @@ export async function appendEventAsync(eventsPath: string, event: AppendTeamEven
  */
 async function appendEventBatchInsideLock(eventsPath: string, queue: BufferedAppend[]): Promise<void> {
 	if (queue.length === 0) return;
+	// P0-2: keep the per-path counter honest for cross-path rotation sampling.
+	tickAppendCounter(eventsPath, queue.length);
 	fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
 
 	// Pre-flight size check (mirrors appendEventInsideLock). We do it once for
@@ -1100,8 +1139,7 @@ function appendEventInsideLock(eventsPath: string, event: AppendTeamEvent): Team
 			logInternalError("event-log.persist-sequence", error, `eventsPath=${eventsPath}`);
 		}
 	}
-	appendCounter++;
-	if (appendCounter % 100 === 0 && needsRotation(eventsPath)) {
+	if (tickAppendCounter(eventsPath) && needsRotation(eventsPath)) {
 		// Round 24 (BUG 1): we are INSIDE withEventLogLockSync here (called via
 		// appendEventInsideLock). The mkdir lock is NOT re-entrant, so calling the
 		// locked compactEventLog would deadlock → 5s timeout → compaction never

package/src/state/{jsonl-writer.ts → event-log/jsonl-writer.ts}

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
-import { logInternalError } from "../utils/internal-error.ts";
-import { redactJsonLine } from "../utils/redaction.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { redactJsonLine } from "../../utils/redaction.ts";
 
 export interface DrainableSource {
 	pause(): void;
@@ -35,8 +35,12 @@ export interface JsonlWriter {
 export function createJsonlWriter(filePath: string | undefined, source: DrainableSource, deps: JsonlWriterDeps = {}): JsonlWriter {
 	if (!filePath) {
 		return {
-			writeLine() {},
-			async close() {},
+			writeLine() {
+				/* no-op: null writer */
+			},
+			async close() {
+				/* no-op: null writer */
+			},
 		};
 	}
 
@@ -46,8 +50,12 @@ export function createJsonlWriter(filePath: string | undefined, source: Drainabl
 		stream = createWriteStream(filePath);
 	} catch {
 		return {
-			writeLine() {},
-			async close() {},
+			writeLine() {
+				/* no-op: stream creation failed */
+			},
+			async close() {
+				/* no-op: stream creation failed */
+			},
 		};
 	}
 

package/src/state/hook-instinct-bridge.ts

@@ -6,13 +6,13 @@
 import { crewHooks } from "../runtime/crew-hooks.ts";
 
 // Lazy-initialized store and paths
-let storeInstance: import("./instinct-store.js").InstinctStore | null = null;
+let storeInstance: import("./stores/instinct-store.js").InstinctStore | null = null;
 let pathsInstance: typeof import("../utils/paths.js") | null = null;
 
 async function getStore() {
 	if (!storeInstance) {
 		// LAZY: defer dynamic import of ./instinct-store.js to its call site.
-		const { InstinctStore } = await import("./instinct-store.js");
+		const { InstinctStore } = await import("./stores/instinct-store.js");
 		// LAZY: defer dynamic import of ../utils/paths.js to its call site.
 		const paths = await import("../utils/paths.js");
 		storeInstance = new InstinctStore(paths.projectCrewRoot(process.cwd()));

package/src/state/{active-run-registry.ts → stores/active-run-registry.ts}

@@ -1,13 +1,13 @@
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { DEFAULT_CACHE, DEFAULT_PATHS } from "../config/defaults.ts";
-import { userCrewRoot } from "../utils/paths.ts";
-import { isSafePathId } from "../utils/safe-paths.ts";
-import { sharedScanCache } from "../utils/scan-cache.ts";
-import { sleepSync } from "../utils/sleep.ts";
-import { atomicWriteJson, isSymlinkSafePath, renameWithRetry } from "./atomic-write.ts";
-import type { TeamRunManifest } from "./types.ts";
+import { DEFAULT_CACHE, DEFAULT_PATHS } from "../../config/defaults.ts";
+import { userCrewRoot } from "../../utils/paths.ts";
+import { isSafePathId } from "../../utils/safe-paths.ts";
+import { sharedScanCache } from "../../utils/scan-cache.ts";
+import { sleepSync } from "../../utils/sleep.ts";
+import { atomicWriteJson, isSymlinkSafePath, renameWithRetry } from "../atomic-write.ts";
+import type { TeamRunManifest } from "../types.ts";
 
 /** Magic bytes prefix for binary registry to prevent deserialization of hostile files. */
 const BINARY_MAGIC = Buffer.from("PICREW2BIN", "utf-8");

package/src/state/{artifact-store.ts → stores/artifact-store.ts}

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { redactSecretString, redactSecrets } from "../utils/redaction.ts";
-import { resolveRealContainedPath } from "../utils/safe-paths.ts";
-import { atomicWriteFile } from "./atomic-write.ts";
-import type { ArtifactDescriptor } from "./types.ts";
+import { redactSecretString, redactSecrets } from "../../utils/redaction.ts";
+import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import { atomicWriteFile } from "../atomic-write.ts";
+import type { ArtifactDescriptor } from "../types.ts";
 
 function hashContent(content: string): string {
 	return createHash("sha256").update(content).digest("hex");
@@ -101,6 +101,64 @@ export function cleanupOldArtifacts(artifactsRoot: string, options: ArtifactClea
 	if (!didCleanup) writeCleanupMarker(artifactsRoot, markerFile);
 }
 
+/**
+ * ST-10: Default TTL for "temporary" retention artifacts (1 hour).
+ * Temporary artifacts (progress, notepad) are short-lived and should not
+ * accumulate. One hour balances cleanup aggressiveness with the possibility
+ * that a long-running task writes periodic progress updates.
+ */
+export const TEMPORARY_RETENTION_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * ST-10: Check whether an artifact descriptor indicates the file should be
+ * pruned (expired).
+ *
+ * Enforces:
+ * - `expiresAt`: if set and now ≥ expiresAt → expired.
+ * - `retention: "temporary"`: if createdAt age ≥ temporaryTtlMs → expired.
+ *   ("run" and "project" retentions are handled by run-level prune and the
+ *   age-based {@link cleanupOldArtifacts}, not by this per-descriptor check.)
+ */
+export function isArtifactExpired(desc: ArtifactDescriptor, nowMs: number, temporaryTtlMs: number = TEMPORARY_RETENTION_TTL_MS): boolean {
+	// Explicit expiresAt takes precedence.
+	if (desc.expiresAt) {
+		const expiryMs = Date.parse(desc.expiresAt);
+		if (Number.isFinite(expiryMs) && nowMs >= expiryMs) return true;
+	}
+	// "temporary" retention has a short TTL.
+	if (desc.retention === "temporary" && desc.createdAt) {
+		const createdMs = Date.parse(desc.createdAt);
+		if (Number.isFinite(createdMs) && nowMs - createdMs >= temporaryTtlMs) return true;
+	}
+	return false;
+}
+
+/**
+ * ST-10: Prune expired artifacts by enforcing ArtifactDescriptor.retention/expiresAt.
+ *
+ * Deletes artifact files whose descriptor indicates expiry (expiresAt passed
+ * or temporary-retention TTL exceeded). Returns the count of files deleted.
+ *
+ * Unlike {@link cleanupOldArtifacts} (which is filesystem age-based on raw
+ * files), this operates on artifact *metadata* from the manifest's `artifacts[]`
+ * and deletes specific expired files via their descriptor `path`.
+ */
+export function pruneExpiredArtifacts(descriptors: ArtifactDescriptor[], options?: { now?: number; temporaryTtlMs?: number }): number {
+	const nowMs = options?.now ?? Date.now();
+	const temporaryTtlMs = options?.temporaryTtlMs ?? TEMPORARY_RETENTION_TTL_MS;
+	let deleted = 0;
+	for (const desc of descriptors) {
+		if (!isArtifactExpired(desc, nowMs, temporaryTtlMs)) continue;
+		try {
+			fs.unlinkSync(desc.path);
+			deleted++;
+		} catch {
+			// Best-effort: file may already be removed or path may be stale.
+		}
+	}
+	return deleted;
+}
+
 function resolveInside(baseDir: string, relativePath: string): string {
 	// Check if baseDir is a symlink on every call to prevent symlink attacks
 	try {

package/src/state/{blob-store.ts → stores/blob-store.ts}

@@ -1,9 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { resolveRealContainedPath } from "../utils/safe-paths.ts";
-import { atomicWriteFile, renameWithRetry } from "./atomic-write.ts";
-import { withFileLockSync } from "./locks.ts";
+import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import { atomicWriteFile, renameWithRetry } from "../atomic-write.ts";
+import { withFileLockSync } from "../coordination/locks.ts";
 
 const SHA256_HEX = /^[a-f0-9]{64}$/i;
 

package/src/state/{health-store.ts → stores/health-store.ts}

@@ -1,8 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ManifestSummary } from "../runtime/task-health.ts";
-import { computeRunHealth } from "../runtime/task-health.ts";
-import { atomicWriteFile } from "./atomic-write.ts";
+import type { ManifestSummary } from "../../runtime/task-health.ts";
+import { computeRunHealth } from "../../runtime/task-health.ts";
+import { atomicWriteFile } from "../atomic-write.ts";
 
 // Relative to the crew root (`<cwd>/.crew`). BUG A fix (pts/2 hang
 // investigation 2026-06-16): this was `.crew/state/health`, which double-joined

package/src/state/{instinct-store.ts → stores/instinct-store.ts}

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { assertSafePathId } from "../utils/safe-paths.ts";
-import { atomicWriteFile } from "./atomic-write.ts";
+import { assertSafePathId } from "../../utils/safe-paths.ts";
+import { atomicWriteFile } from "../atomic-write.ts";
 
 /**
  * Represents a learned instinct that guides agent behavior.
@@ -272,4 +272,4 @@ export class InstinctStore {
 export {
 	getGlobalStorageDir,
 	getProjectStorageDir,
-} from "../utils/project-detector.ts";
+} from "../../utils/project-detector.ts";

package/src/state/{observation-store.ts → stores/observation-store.ts}

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
-import { logInternalError } from "../utils/internal-error.ts";
-import { atomicWriteJson } from "./atomic-write.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { atomicWriteJson } from "../atomic-write.ts";
 
 // ── Types ────────────────────────────────────────────────────────────────
 

package/src/state/{run-cache.ts → stores/run-cache.ts}

@@ -1,10 +1,10 @@
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { projectCrewRoot } from "../utils/paths.ts";
-import { atomicWriteJson } from "./atomic-write.ts";
-import { withFileLockSync } from "./locks.ts";
-import type { TeamTaskState } from "./types.ts";
+import { projectCrewRoot } from "../../utils/paths.ts";
+import { atomicWriteJson } from "../atomic-write.ts";
+import { withFileLockSync } from "../coordination/locks.ts";
+import type { TeamTaskState } from "../types.ts";
 
 const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 

package/src/state/{run-graph.ts → stores/run-graph.ts}

@@ -1,9 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { projectCrewRoot } from "../utils/paths.ts";
-import { assertSafePathId } from "../utils/safe-paths.ts";
-import { atomicWriteFile } from "./atomic-write.ts";
-import type { TeamRunManifest, TeamTaskState } from "./types.ts";
+import { projectCrewRoot } from "../../utils/paths.ts";
+import { assertSafePathId } from "../../utils/safe-paths.ts";
+import { atomicWriteFile } from "../atomic-write.ts";
+import type { TeamRunManifest, TeamTaskState } from "../types.ts";
 
 export interface RunGraphNode {
 	id: string;

package/src/state/{run-metrics.ts → stores/run-metrics.ts}

@@ -1,8 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { projectCrewRoot } from "../utils/paths.ts";
-import { assertSafePathId } from "../utils/safe-paths.ts";
-import { atomicWriteJson, readJsonFile } from "./atomic-write.ts";
+import { projectCrewRoot } from "../../utils/paths.ts";
+import { assertSafePathId } from "../../utils/safe-paths.ts";
+import { atomicWriteJson, readJsonFile } from "../atomic-write.ts";
 import { loadRunManifestById } from "./state-store.ts";
 
 /**