@tangle-network/agent-runtime 0.140.0 → 0.141.0

package/dist/durable.d.ts

@@ -1,4 +1,6 @@
-import { x as NodeId } from "./types-D4arYjUl.js";
+import { Oo as SupervisorProfile, mo as supervise, uo as SuperviseOptions } from "./index-D4dUTLcs.js";
+import { l as RuntimeHooks, o as RuntimeHookEvent, r as RuntimeDecisionPoint } from "./runtime-hooks-Bj6wJHlH.js";
+import { x as NodeId } from "./types-CNGHfnk3.js";
 //#region src/durable/chat-engine.d.ts
 /**
  * `handleChatTurn` is a framework-neutral chat-turn HTTP orchestrator.
@@ -131,6 +133,176 @@ declare function deriveExecutionId(input: {
   turnIndex: number;
 }): string;
 //#endregion
+//#region src/durable/observer-journal.d.ts
+type ObserverRecordKind = 'event' | 'decision';
+/**
+ * One immutable record in the observer plane. `sequence` is journal order, not
+ * execution order; causal/runtime order remains available on the underlying event.
+ * `previousDigest` + `digest` make deletion, reordering, or mutation detectable.
+ */
+interface ObserverRecord {
+  readonly schemaVersion: 1;
+  readonly pursuitId: string;
+  readonly sequence: number;
+  readonly kind: ObserverRecordKind;
+  readonly observedAt: number;
+  readonly previousDigest?: string;
+  readonly event?: RuntimeHookEvent;
+  readonly decision?: RuntimeDecisionPoint;
+  readonly digest: string;
+}
+interface ObserverJournal {
+  appendEvent(event: RuntimeHookEvent): Promise<ObserverRecord>;
+  appendDecision(point: RuntimeDecisionPoint): Promise<ObserverRecord>;
+  read(): Promise<readonly ObserverRecord[]>;
+  hooks(): RuntimeHooks;
+}
+/**
+ * Durable, append-only third-person history for one concrete Runtime execution.
+ * It consumes Runtime's existing hook stream and does not participate in execution
+ * decisions. A broken observer therefore cannot change what an agent is allowed to do.
+ *
+ * The write discipline deliberately matches `FileSpawnJournal`: serialized appends,
+ * torn-tail recovery, short-write handling, and fsync before acknowledgement. One
+ * execution owns one journal file; higher-level pursuit aggregation joins isolated
+ * journals by `pursuitId` instead of making independent processes share a write head.
+ */
+declare class FileObserverJournal implements ObserverJournal {
+  readonly path: string;
+  readonly pursuitId: string;
+  private tail;
+  private initialized;
+  private sequence;
+  private previousDigest;
+  private appendFailure;
+  constructor(path: string, pursuitId: string);
+  hooks(): RuntimeHooks;
+  appendEvent(event: RuntimeHookEvent): Promise<ObserverRecord>;
+  appendDecision(point: RuntimeDecisionPoint): Promise<ObserverRecord>;
+  read(): Promise<readonly ObserverRecord[]>;
+  private enqueue;
+  private initialize;
+  private readExistingUnsafe;
+  private writeRecord;
+  private assertComplete;
+}
+/** Verify identity, monotonic sequence, payload shape, and the complete digest chain. */
+declare function verifyObserverRecords(records: readonly ObserverRecord[], pursuitId?: string): readonly ObserverRecord[];
+/** Compute the canonical SHA-256 digest for an unsigned observer record. */
+declare function observerRecordDigest(record: Omit<ObserverRecord, 'digest'>): string;
+/** Build the canonical durable observer hook in one call. */
+declare function createFileObserverHooks(path: string, pursuitId: string): {
+  readonly journal: FileObserverJournal;
+  readonly hooks: RuntimeHooks;
+};
+//#endregion
+//#region src/durable/observer-projection.d.ts
+type PursuitRunStatus = 'running' | 'done' | 'failed';
+interface PursuitRunProjection {
+  readonly runId: string;
+  readonly status: PursuitRunStatus;
+  readonly settledAt?: number;
+  readonly error?: string;
+  readonly firstSequence: number;
+  readonly lastSequence: number;
+  readonly firstObservedAt: number;
+  readonly lastObservedAt: number;
+  readonly eventCount: number;
+  readonly decisionCount: number;
+  readonly targets: Readonly<Record<string, number>>;
+  readonly decisions: Readonly<Record<string, number>>;
+}
+type PursuitNodeStatus = 'running' | 'done' | 'down';
+interface PursuitNodeProjection {
+  readonly id: string;
+  readonly parentId?: string;
+  /** Node ids are scoped to this concrete Runtime tree; `(runId,id)` is identity. */
+  readonly runId: string;
+  readonly label?: string;
+  readonly runtime?: string;
+  readonly depth?: number;
+  readonly assignmentId?: string;
+  readonly identity?: unknown;
+  readonly budget?: unknown;
+  readonly status: PursuitNodeStatus;
+  readonly settledAt?: number;
+  readonly spent?: unknown;
+  readonly outRef?: string;
+  readonly score?: number;
+  readonly valid?: boolean;
+  readonly reason?: string;
+  readonly infra?: boolean;
+  readonly wait?: unknown;
+  readonly firstSequence: number;
+  readonly lastSequence: number;
+  readonly firstObservedAt: number;
+  readonly lastObservedAt: number;
+  readonly eventCount: number;
+}
+interface PursuitProjection {
+  readonly pursuitId: string;
+  /** Number of records in this concrete execution journal. */
+  readonly sequence: number;
+  /** Digest-chain tip for this concrete execution journal. */
+  readonly chainTip: string;
+  readonly firstObservedAt: number;
+  readonly lastObservedAt: number;
+  readonly runs: readonly PursuitRunProjection[];
+  readonly nodes: readonly PursuitNodeProjection[];
+  readonly eventCount: number;
+  readonly decisionCount: number;
+}
+/**
+ * Fold one append-only execution journal into a deterministic operator projection.
+ *
+ * This is intentionally a READ model, not another state machine: it does not own
+ * execution, cannot steer agents, and can be rebuilt from the journal at any time.
+ * Projection verifies the complete hash chain first, so an operator view can never
+ * silently render a mutated or reordered observer history as trustworthy state.
+ *
+ * Topology comes only from Runtime's canonical `agent.spawn` facts. Terminal node
+ * state comes only from `agent.child`; concrete run state comes only from the root
+ * `agent.run` lifecycle emitted by `supervisePursuit`. Node identity is scoped to the
+ * concrete Runtime run so independent trees may both contain `root:s0` without aliasing.
+ */
+declare function projectPursuit(records: readonly ObserverRecord[]): PursuitProjection;
+//#endregion
+//#region src/durable/supervise-pursuit.d.ts
+interface SupervisePursuitOptions extends SuperviseOptions {
+  /** Stable objective identity spanning concrete Runtime runs. */
+  readonly pursuitId: string;
+  /**
+   * One concrete Runtime execution owns one durable directory and observer journal.
+   * A pursuit spanning several runs reuses `pursuitId` across distinct `runDir`s;
+   * Intelligence joins those isolated projections without a shared write head.
+   */
+  readonly runDir: string;
+}
+interface SupervisedPursuitResult<Result> {
+  readonly result: Result;
+  readonly pursuit: PursuitProjection;
+  readonly observerPath: string;
+}
+/** A failed Runtime execution whose complete third-person projection was retained. */
+declare class SupervisePursuitError extends Error {
+  readonly pursuit: PursuitProjection;
+  readonly observerPath: string;
+  constructor(cause: unknown, pursuit: PursuitProjection, observerPath: string);
+}
+/**
+ * One-call durable pursuit execution over the canonical `supervise()` kernel.
+ *
+ * This is an adapter, not a second executor: it composes a durable third-person
+ * observer into Runtime's existing recursive hook stream and then rebuilds the
+ * operator projection after the same `supervise()` call settles. Agents never
+ * receive the observer path or projection and their behavior does not depend on it.
+ *
+ * Every concrete execution writes only inside its own `runDir`. Cross-run pursuit
+ * aggregation is therefore lock-free at the observer layer: reuse `pursuitId` across
+ * run directories and let Intelligence join the independently verified projections.
+ */
+declare function supervisePursuit(profile: SupervisorProfile, task: unknown, opts: SupervisePursuitOptions): Promise<SupervisedPursuitResult<Awaited<ReturnType<typeof supervise>>>>;
+//#endregion
 //#region src/durable/supervision-discovery.d.ts
 interface DurableCoordinationStreamIdentity {
   readonly runId: string;
@@ -163,5 +335,5 @@ interface DurableSupervisionDiscovery {
  */
 declare function discoverDurableSupervisionRun(runDir: string): Promise<DurableSupervisionDiscovery>;
 //#endregion
-export { type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, type DurableCoordinationStreamIdentity, type DurableSupervisionDiscovery, type RunChatTurnInput, deriveExecutionId, discoverDurableSupervisionRun, handleChatTurn };
+export { type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, type DurableCoordinationStreamIdentity, type DurableSupervisionDiscovery, FileObserverJournal, type ObserverJournal, type ObserverRecord, type ObserverRecordKind, type PursuitNodeProjection, type PursuitNodeStatus, type PursuitProjection, type PursuitRunProjection, type PursuitRunStatus, type RunChatTurnInput, SupervisePursuitError, type SupervisePursuitOptions, type SupervisedPursuitResult, createFileObserverHooks, deriveExecutionId, discoverDurableSupervisionRun, handleChatTurn, observerRecordDigest, projectPursuit, supervisePursuit, verifyObserverRecords };
 //# sourceMappingURL=durable.d.ts.map

package/dist/durable.js

@@ -1,5 +1,9 @@
-import { t as parseCommittedJsonLines } from "./jsonl-file-DtxhdAkZ.js";
+import { d as prepareJsonlAppend, f as writeAllBytes, u as parseCommittedJsonLines } from "./spawn-journal-D2HKUImC.js";
+import { a as withPursuitContext, t as composeRuntimeHooks } from "./runtime-hooks-tXpAarhW.js";
+import { n as supervise } from "./supervise-CqN9ThOr.js";
+import { createHash } from "node:crypto";
 import { resolve } from "node:path";
+import { readFile } from "node:fs/promises";
 //#region src/durable/chat-engine.ts
 const encoder = new TextEncoder();
 function encodeLine(event) {
@@ -121,6 +125,433 @@ function deriveExecutionId(input) {
 	return executionId;
 }
 //#endregion
+//#region src/durable/observer-journal.ts
+/**
+* Durable, append-only third-person history for one concrete Runtime execution.
+* It consumes Runtime's existing hook stream and does not participate in execution
+* decisions. A broken observer therefore cannot change what an agent is allowed to do.
+*
+* The write discipline deliberately matches `FileSpawnJournal`: serialized appends,
+* torn-tail recovery, short-write handling, and fsync before acknowledgement. One
+* execution owns one journal file; higher-level pursuit aggregation joins isolated
+* journals by `pursuitId` instead of making independent processes share a write head.
+*/
+var FileObserverJournal = class {
+	path;
+	pursuitId;
+	tail = Promise.resolve();
+	initialized = false;
+	sequence = 0;
+	previousDigest;
+	appendFailure;
+	constructor(path, pursuitId) {
+		const stableId = pursuitId.trim();
+		if (stableId.length === 0) throw new TypeError("FileObserverJournal: pursuitId must be non-empty");
+		this.path = resolve(path);
+		this.pursuitId = stableId;
+	}
+	hooks() {
+		return withPursuitContext(this.pursuitId, {
+			onEvent: (event) => this.appendEvent(event).then(() => void 0),
+			onDecisionPoint: (point) => this.appendDecision(point).then(() => void 0)
+		});
+	}
+	appendEvent(event) {
+		return this.enqueue("event", event);
+	}
+	appendDecision(point) {
+		return this.enqueue("decision", point);
+	}
+	async read() {
+		await this.tail;
+		this.assertComplete();
+		let text;
+		try {
+			text = await readFile(this.path, "utf8");
+		} catch (error) {
+			if (isNoEnt(error)) return [];
+			throw error;
+		}
+		return verifyObserverRecords(parseCommittedJsonLines(text, this.path), this.pursuitId);
+	}
+	enqueue(kind, value) {
+		if (value.pursuitId !== this.pursuitId) return Promise.reject(/* @__PURE__ */ new Error(`FileObserverJournal: ${kind} pursuitId ${String(value.pursuitId)} does not match ${this.pursuitId}`));
+		let result;
+		const operation = this.tail.then(async () => {
+			this.assertComplete();
+			try {
+				await this.initialize();
+			} catch (error) {
+				this.appendFailure ??= toError(error);
+				throw error;
+			}
+			const unsigned = {
+				schemaVersion: 1,
+				pursuitId: this.pursuitId,
+				sequence: this.sequence + 1,
+				kind,
+				observedAt: Date.now(),
+				...this.previousDigest ? { previousDigest: this.previousDigest } : {},
+				...kind === "event" ? { event: value } : { decision: value }
+			};
+			const record = Object.freeze({
+				...unsigned,
+				digest: observerRecordDigest(unsigned)
+			});
+			try {
+				await this.writeRecord(record);
+			} catch (error) {
+				this.appendFailure ??= toError(error);
+				throw error;
+			}
+			this.sequence = record.sequence;
+			this.previousDigest = record.digest;
+			result = record;
+		});
+		this.tail = operation.then(() => void 0, () => void 0);
+		return operation.then(() => {
+			if (!result) throw new Error("FileObserverJournal: append completed without a record");
+			return result;
+		});
+	}
+	async initialize() {
+		if (this.initialized) return;
+		const tail = verifyObserverRecords(await this.readExistingUnsafe(), this.pursuitId).at(-1);
+		this.sequence = tail?.sequence ?? 0;
+		this.previousDigest = tail?.digest;
+		this.initialized = true;
+	}
+	async readExistingUnsafe() {
+		let text;
+		try {
+			text = await readFile(this.path, "utf8");
+		} catch (error) {
+			if (isNoEnt(error)) return [];
+			throw error;
+		}
+		return parseCommittedJsonLines(text, this.path);
+	}
+	async writeRecord(record) {
+		const fs = await import("node:fs/promises");
+		const path = await import("node:path");
+		await fs.mkdir(path.dirname(this.path), { recursive: true });
+		const needsSeparator = await prepareJsonlAppend(this.path);
+		const handle = await fs.open(this.path, "a");
+		try {
+			await writeAllBytes(handle, `${needsSeparator ? "\n" : ""}${JSON.stringify(record)}\n`);
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+	}
+	assertComplete() {
+		if (!this.appendFailure) return;
+		throw new Error("FileObserverJournal: a prior durable append failed; observer completeness is unknown", { cause: this.appendFailure });
+	}
+};
+/** Verify identity, monotonic sequence, payload shape, and the complete digest chain. */
+function verifyObserverRecords(records, pursuitId) {
+	let previousDigest;
+	let expectedSequence = 1;
+	for (const record of records) {
+		if (record.schemaVersion !== 1) throw new Error("observer journal: unsupported schemaVersion");
+		if (pursuitId !== void 0 && record.pursuitId !== pursuitId) throw new Error(`observer journal: pursuit identity mismatch at sequence ${record.sequence}`);
+		if (record.sequence !== expectedSequence) throw new Error(`observer journal: non-contiguous sequence ${record.sequence}; expected ${expectedSequence}`);
+		if (record.previousDigest !== previousDigest) throw new Error(`observer journal: digest-chain break at sequence ${record.sequence}`);
+		if (record.kind === "event" === (record.event === void 0)) throw new Error(`observer journal: invalid event payload at sequence ${record.sequence}`);
+		if (record.kind === "decision" === (record.decision === void 0)) throw new Error(`observer journal: invalid decision payload at sequence ${record.sequence}`);
+		if (record.event !== void 0 && record.event.pursuitId !== record.pursuitId) throw new Error(`observer journal: nested event pursuit mismatch at sequence ${record.sequence}`);
+		if (record.decision !== void 0 && record.decision.pursuitId !== record.pursuitId) throw new Error(`observer journal: nested decision pursuit mismatch at sequence ${record.sequence}`);
+		const { digest, ...unsigned } = record;
+		if (digest !== observerRecordDigest(unsigned)) throw new Error(`observer journal: digest mismatch at sequence ${record.sequence}`);
+		previousDigest = digest;
+		expectedSequence += 1;
+	}
+	return Object.freeze([...records]);
+}
+/** Compute the canonical SHA-256 digest for an unsigned observer record. */
+function observerRecordDigest(record) {
+	return createHash("sha256").update(JSON.stringify(record)).digest("hex");
+}
+/** Build the canonical durable observer hook in one call. */
+function createFileObserverHooks(path, pursuitId) {
+	const journal = new FileObserverJournal(path, pursuitId);
+	return {
+		journal,
+		hooks: journal.hooks()
+	};
+}
+function isNoEnt(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function toError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+//#endregion
+//#region src/durable/observer-projection.ts
+/**
+* Fold one append-only execution journal into a deterministic operator projection.
+*
+* This is intentionally a READ model, not another state machine: it does not own
+* execution, cannot steer agents, and can be rebuilt from the journal at any time.
+* Projection verifies the complete hash chain first, so an operator view can never
+* silently render a mutated or reordered observer history as trustworthy state.
+*
+* Topology comes only from Runtime's canonical `agent.spawn` facts. Terminal node
+* state comes only from `agent.child`; concrete run state comes only from the root
+* `agent.run` lifecycle emitted by `supervisePursuit`. Node identity is scoped to the
+* concrete Runtime run so independent trees may both contain `root:s0` without aliasing.
+*/
+function projectPursuit(records) {
+	if (records.length === 0) throw new TypeError("projectPursuit: at least one observer record is required");
+	const pursuitId = records[0].pursuitId;
+	const verified = verifyObserverRecords(records, pursuitId);
+	const runs = /* @__PURE__ */ new Map();
+	const nodes = /* @__PURE__ */ new Map();
+	let eventCount = 0;
+	let decisionCount = 0;
+	for (const record of verified) {
+		const observed = record.event ?? record.decision;
+		if (!observed) throw new Error(`projectPursuit: record ${record.sequence} has no observation`);
+		const run = getRun(runs, observed.runId, record);
+		run.lastSequence = record.sequence;
+		run.lastObservedAt = record.observedAt;
+		if (record.event) {
+			eventCount += 1;
+			run.eventCount += 1;
+			increment(run.targets, record.event.target);
+			projectRunActivity(run, record);
+			projectSpawnNode(nodes, record);
+			projectNodeActivity(nodes, record);
+		} else if (record.decision) {
+			decisionCount += 1;
+			run.decisionCount += 1;
+			increment(run.decisions, record.decision.kind);
+		}
+	}
+	const first = verified[0];
+	const last = verified.at(-1);
+	return Object.freeze({
+		pursuitId,
+		sequence: last.sequence,
+		chainTip: last.digest,
+		firstObservedAt: first.observedAt,
+		lastObservedAt: last.observedAt,
+		runs: Object.freeze([...runs.values()].sort((a, b) => a.firstSequence - b.firstSequence || a.runId.localeCompare(b.runId)).map(freezeRun)),
+		nodes: Object.freeze([...nodes.values()].sort((a, b) => a.firstSequence - b.firstSequence || a.runId.localeCompare(b.runId) || a.id.localeCompare(b.id)).map(freezeNode)),
+		eventCount,
+		decisionCount
+	});
+}
+function getRun(runs, runId, record) {
+	const existing = runs.get(runId);
+	if (existing) return existing;
+	const created = {
+		runId,
+		status: "running",
+		firstSequence: record.sequence,
+		lastSequence: record.sequence,
+		firstObservedAt: record.observedAt,
+		lastObservedAt: record.observedAt,
+		eventCount: 0,
+		decisionCount: 0,
+		targets: {},
+		decisions: {}
+	};
+	runs.set(runId, created);
+	return created;
+}
+function projectRunActivity(run, record) {
+	const event = record.event;
+	if (event?.target !== "agent.run") return;
+	const payload = objectRecord(event.payload);
+	const status = stringField(payload, "status");
+	if (event.phase === "after" || status === "done") {
+		run.status = "done";
+		run.settledAt = record.observedAt;
+		return;
+	}
+	if (event.phase !== "error" && status !== "failed") return;
+	run.status = "failed";
+	run.settledAt = record.observedAt;
+	const error = stringField(payload, "error");
+	if (error) run.error = error;
+}
+function nodeKey(runId, nodeId) {
+	return `${runId}\u0000${nodeId}`;
+}
+function projectSpawnNode(nodes, record) {
+	const event = record.event;
+	if (event?.target !== "agent.spawn") return;
+	const payload = objectRecord(event.payload);
+	const childId = stringField(payload, "childId");
+	if (!childId) return;
+	const key = nodeKey(event.runId, childId);
+	const existing = nodes.get(key);
+	if (existing) {
+		existing.lastSequence = record.sequence;
+		existing.lastObservedAt = record.observedAt;
+		existing.eventCount += 1;
+		return;
+	}
+	const label = stringField(payload, "label");
+	const runtime = stringField(payload, "runtime");
+	const depth = numberField(payload, "depth");
+	const assignmentId = stringField(payload, "assignmentId");
+	nodes.set(key, {
+		id: childId,
+		...event.parentId ? { parentId: event.parentId } : {},
+		runId: event.runId,
+		...label ? { label } : {},
+		...runtime ? { runtime } : {},
+		...depth !== void 0 ? { depth } : {},
+		...assignmentId ? { assignmentId } : {},
+		...payload && Object.hasOwn(payload, "identity") ? { identity: payload.identity } : {},
+		...payload && Object.hasOwn(payload, "budget") ? { budget: payload.budget } : {},
+		status: "running",
+		firstSequence: record.sequence,
+		lastSequence: record.sequence,
+		firstObservedAt: record.observedAt,
+		lastObservedAt: record.observedAt,
+		eventCount: 1
+	});
+}
+function projectNodeActivity(nodes, record) {
+	const event = record.event;
+	if (event === void 0) return;
+	if (event.target === "agent.spawn") return;
+	const payload = objectRecord(event.payload);
+	const nodeId = stringField(payload, "childId") ?? stringField(payload, "nodeId") ?? stringField(payload, "workerId");
+	if (!nodeId) return;
+	const node = nodes.get(nodeKey(event.runId, nodeId));
+	if (!node) return;
+	node.lastSequence = record.sequence;
+	node.lastObservedAt = record.observedAt;
+	node.eventCount += 1;
+	if (event.target !== "agent.child") return;
+	const status = stringField(payload, "status");
+	if (status !== "done" && status !== "down") return;
+	node.status = status;
+	node.settledAt = record.observedAt;
+	if (payload && Object.hasOwn(payload, "spent")) node.spent = payload.spent;
+	const outRef = stringField(payload, "outRef");
+	if (outRef) node.outRef = outRef;
+	const score = numberField(payload, "score");
+	if (score !== void 0) node.score = score;
+	const valid = booleanField(payload, "valid");
+	if (valid !== void 0) node.valid = valid;
+	const reason = stringField(payload, "reason");
+	if (reason) node.reason = reason;
+	const infra = booleanField(payload, "infra");
+	if (infra !== void 0) node.infra = infra;
+	if (payload && Object.hasOwn(payload, "wait")) node.wait = payload.wait;
+}
+function freezeRun(run) {
+	return Object.freeze({
+		...run,
+		targets: Object.freeze({ ...run.targets }),
+		decisions: Object.freeze({ ...run.decisions })
+	});
+}
+function freezeNode(node) {
+	return Object.freeze({ ...node });
+}
+function increment(target, key) {
+	target[key] = (target[key] ?? 0) + 1;
+}
+function objectRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function stringField(value, key) {
+	const field = value?.[key];
+	return typeof field === "string" && field.length > 0 ? field : void 0;
+}
+function numberField(value, key) {
+	const field = value?.[key];
+	return typeof field === "number" && Number.isFinite(field) ? field : void 0;
+}
+function booleanField(value, key) {
+	const field = value?.[key];
+	return typeof field === "boolean" ? field : void 0;
+}
+//#endregion
+//#region src/durable/supervise-pursuit.ts
+/** A failed Runtime execution whose complete third-person projection was retained. */
+var SupervisePursuitError = class extends Error {
+	pursuit;
+	observerPath;
+	constructor(cause, pursuit, observerPath) {
+		super(`supervisePursuit: ${errorMessage(cause)}`, { cause });
+		this.name = "SupervisePursuitError";
+		this.pursuit = pursuit;
+		this.observerPath = observerPath;
+	}
+};
+/**
+* One-call durable pursuit execution over the canonical `supervise()` kernel.
+*
+* This is an adapter, not a second executor: it composes a durable third-person
+* observer into Runtime's existing recursive hook stream and then rebuilds the
+* operator projection after the same `supervise()` call settles. Agents never
+* receive the observer path or projection and their behavior does not depend on it.
+*
+* Every concrete execution writes only inside its own `runDir`. Cross-run pursuit
+* aggregation is therefore lock-free at the observer layer: reuse `pursuitId` across
+* run directories and let Intelligence join the independently verified projections.
+*/
+async function supervisePursuit(profile, task, opts) {
+	const pursuitId = opts.pursuitId.trim();
+	if (pursuitId.length === 0) throw new TypeError("supervisePursuit: pursuitId must be non-empty");
+	const runDir = opts.runDir.trim();
+	if (runDir.length === 0) throw new TypeError("supervisePursuit: runDir must be non-empty");
+	const observerPath = resolve(runDir, "observer.jsonl");
+	const { pursuitId: _pursuitId, hooks, ...superviseOptions } = opts;
+	const observer = createFileObserverHooks(observerPath, pursuitId);
+	const runId = superviseOptions.runId ?? "supervise";
+	const now = superviseOptions.now ?? Date.now;
+	await observer.journal.appendEvent(rootEvent(pursuitId, runId, "before", now()));
+	try {
+		const result = await supervise(profile, task, {
+			...superviseOptions,
+			hooks: withPursuitContext(pursuitId, composeRuntimeHooks(observer.hooks, hooks))
+		});
+		await observer.journal.appendEvent(rootEvent(pursuitId, runId, "after", now(), { status: "done" }));
+		return Object.freeze({
+			result,
+			pursuit: projectPursuit(await observer.journal.read()),
+			observerPath
+		});
+	} catch (error) {
+		let pursuit;
+		let observerError;
+		try {
+			await observer.journal.appendEvent(rootEvent(pursuitId, runId, "error", now(), {
+				status: "failed",
+				error: errorMessage(error)
+			}));
+			pursuit = projectPursuit(await observer.journal.read());
+		} catch (failure) {
+			observerError = failure;
+		}
+		if (observerError !== void 0 || pursuit === void 0) throw new Error("supervisePursuit: Runtime failed and durable observer completeness could not be proven", { cause: new AggregateError(observerError === void 0 ? [error] : [error, observerError]) });
+		throw new SupervisePursuitError(error, pursuit, observerPath);
+	}
+}
+function rootEvent(pursuitId, runId, phase, timestamp, payload) {
+	return Object.freeze({
+		id: `${runId}:pursuit:${phase}:${timestamp}`,
+		pursuitId,
+		runId,
+		target: "agent.run",
+		phase,
+		timestamp,
+		...payload ? { payload: Object.freeze({ ...payload }) } : {}
+	});
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
 //#region src/durable/supervision-discovery.ts
 /**
 * Discover the stable identities recorded by Runtime's durable supervision
@@ -200,6 +631,6 @@ function isNoEntError(error) {
 	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
 //#endregion
-export { deriveExecutionId, discoverDurableSupervisionRun, handleChatTurn };
+export { FileObserverJournal, SupervisePursuitError, createFileObserverHooks, deriveExecutionId, discoverDurableSupervisionRun, handleChatTurn, observerRecordDigest, projectPursuit, supervisePursuit, verifyObserverRecords };
 
 //# sourceMappingURL=durable.js.map