@usecontextlayer/ctxe 0.4.11 → 0.4.13

package/dist/cli.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7487993d-7bca-5e7a-92f4-fc03dc11a776")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ef06741d-8451-516d-a05b-dd7da1f526a8")}catch(e){}}();
 import { createRequire } from "node:module";
 import * as Sentry from "@sentry/node";
 import * as xi from "node:fs";
 import { appendFileSync, createReadStream, createWriteStream, existsSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { constants, homedir, tmpdir } from "node:os";
-import path, { posix, sep, win32 } from "node:path";
+import path, { posix, resolve, sep, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 import fs, { lstatSync, readdir, readdirSync, readlinkSync, realpathSync as realpathSync$1 } from "fs";
 import { access, copyFile, cp, lstat, mkdir, mkdtemp, readFile, readdir as readdir$1, readlink, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
@@ -59,7 +59,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 //#endregion
 //#region package.json
-var version$1 = "0.4.11";
+var version$1 = "0.4.13";
 
 //#endregion
 //#region sentry.ts
@@ -7283,6 +7283,74 @@ function _getDefaultLogLevel() {
 }
 const consola = createConsola();
 
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/rng.js
+const rnds8 = new Uint8Array(16);
+function rng() {
+	return crypto.getRandomValues(rnds8);
+}
+
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/stringify.js
+const byteToHex = [];
+for (let i = 0; i < 256; ++i) byteToHex.push((i + 256).toString(16).slice(1));
+function unsafeStringify(arr, offset = 0) {
+	return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
+}
+
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/v7.js
+const _state = {};
+function v7(options, buf, offset) {
+	let bytes;
+	if (options) bytes = v7Bytes(options.random ?? options.rng?.() ?? rng(), options.msecs, options.seq, buf, offset);
+	else {
+		const now = Date.now();
+		const rnds = rng();
+		updateV7State(_state, now, rnds);
+		bytes = v7Bytes(rnds, _state.msecs, _state.seq, buf, offset);
+	}
+	return buf ?? unsafeStringify(bytes);
+}
+function updateV7State(state, now, rnds) {
+	state.msecs ??= -Infinity;
+	state.seq ??= 0;
+	if (now > state.msecs) {
+		state.seq = rnds[6] << 23 | rnds[7] << 16 | rnds[8] << 8 | rnds[9];
+		state.msecs = now;
+	} else {
+		state.seq = state.seq + 1 | 0;
+		if (state.seq === 0) state.msecs++;
+	}
+	return state;
+}
+function v7Bytes(rnds, msecs, seq, buf, offset = 0) {
+	if (rnds.length < 16) throw new Error("Random bytes length must be >= 16");
+	if (!buf) {
+		buf = new Uint8Array(16);
+		offset = 0;
+	} else if (offset < 0 || offset + 16 > buf.length) throw new RangeError(`UUID byte range ${offset}:${offset + 15} is out of buffer bounds`);
+	msecs ??= Date.now();
+	seq ??= rnds[6] * 127 << 24 | rnds[7] << 16 | rnds[8] << 8 | rnds[9];
+	buf[offset++] = msecs / 1099511627776 & 255;
+	buf[offset++] = msecs / 4294967296 & 255;
+	buf[offset++] = msecs / 16777216 & 255;
+	buf[offset++] = msecs / 65536 & 255;
+	buf[offset++] = msecs / 256 & 255;
+	buf[offset++] = msecs & 255;
+	buf[offset++] = 112 | seq >>> 28 & 15;
+	buf[offset++] = seq >>> 20 & 255;
+	buf[offset++] = 128 | seq >>> 14 & 63;
+	buf[offset++] = seq >>> 6 & 255;
+	buf[offset++] = seq << 2 & 255 | rnds[10] & 3;
+	buf[offset++] = rnds[11];
+	buf[offset++] = rnds[12];
+	buf[offset++] = rnds[13];
+	buf[offset++] = rnds[14];
+	buf[offset++] = rnds[15];
+	return buf;
+}
+
 //#endregion
 //#region ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/core/core.js
 var _a$1;
@@ -17926,74 +17994,6 @@ const execaNode = createExeca(mapNode);
 const $ = createExeca(mapScriptAsync, {}, deepScriptOptions, setScriptSync);
 const { sendMessage, getOneMessage, getEachMessage, getCancelSignal } = getIpcExport();
 
-//#endregion
-//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/rng.js
-const rnds8 = new Uint8Array(16);
-function rng() {
-	return crypto.getRandomValues(rnds8);
-}
-
-//#endregion
-//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/stringify.js
-const byteToHex = [];
-for (let i = 0; i < 256; ++i) byteToHex.push((i + 256).toString(16).slice(1));
-function unsafeStringify(arr, offset = 0) {
-	return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
-}
-
-//#endregion
-//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/v7.js
-const _state = {};
-function v7(options, buf, offset) {
-	let bytes;
-	if (options) bytes = v7Bytes(options.random ?? options.rng?.() ?? rng(), options.msecs, options.seq, buf, offset);
-	else {
-		const now = Date.now();
-		const rnds = rng();
-		updateV7State(_state, now, rnds);
-		bytes = v7Bytes(rnds, _state.msecs, _state.seq, buf, offset);
-	}
-	return buf ?? unsafeStringify(bytes);
-}
-function updateV7State(state, now, rnds) {
-	state.msecs ??= -Infinity;
-	state.seq ??= 0;
-	if (now > state.msecs) {
-		state.seq = rnds[6] << 23 | rnds[7] << 16 | rnds[8] << 8 | rnds[9];
-		state.msecs = now;
-	} else {
-		state.seq = state.seq + 1 | 0;
-		if (state.seq === 0) state.msecs++;
-	}
-	return state;
-}
-function v7Bytes(rnds, msecs, seq, buf, offset = 0) {
-	if (rnds.length < 16) throw new Error("Random bytes length must be >= 16");
-	if (!buf) {
-		buf = new Uint8Array(16);
-		offset = 0;
-	} else if (offset < 0 || offset + 16 > buf.length) throw new RangeError(`UUID byte range ${offset}:${offset + 15} is out of buffer bounds`);
-	msecs ??= Date.now();
-	seq ??= rnds[6] * 127 << 24 | rnds[7] << 16 | rnds[8] << 8 | rnds[9];
-	buf[offset++] = msecs / 1099511627776 & 255;
-	buf[offset++] = msecs / 4294967296 & 255;
-	buf[offset++] = msecs / 16777216 & 255;
-	buf[offset++] = msecs / 65536 & 255;
-	buf[offset++] = msecs / 256 & 255;
-	buf[offset++] = msecs & 255;
-	buf[offset++] = 112 | seq >>> 28 & 15;
-	buf[offset++] = seq >>> 20 & 255;
-	buf[offset++] = 128 | seq >>> 14 & 63;
-	buf[offset++] = seq >>> 6 & 255;
-	buf[offset++] = seq << 2 & 255 | rnds[10] & 3;
-	buf[offset++] = rnds[11];
-	buf[offset++] = rnds[12];
-	buf[offset++] = rnds[13];
-	buf[offset++] = rnds[14];
-	buf[offset++] = rnds[15];
-	return buf;
-}
-
 //#endregion
 //#region ../../node_modules/.pnpm/kind-of@6.0.3/node_modules/kind-of/index.js
 var require_kind_of = /* @__PURE__ */ __commonJSMin(((exports, module) => {
@@ -29629,6 +29629,44 @@ function osUsername() {
 
 //#endregion
 //#region ../engine/dist/index.mjs
+function msToIso(ms) {
+	return new Date(ms).toISOString();
+}
+const isoMsSchema = string().transform((value, ctx) => {
+	const ms = Date.parse(value);
+	if (Number.isNaN(ms)) {
+		ctx.addIssue({
+			code: "custom",
+			message: "must be an ISO-8601 timestamp"
+		});
+		return NEVER;
+	}
+	return ms;
+});
+function isoToMs(iso, label) {
+	const result = isoMsSchema.safeParse(iso);
+	if (!result.success) throw new Error(`${label} is not a valid ISO-8601 timestamp: ${iso}`);
+	return result.data;
+}
+function resolveAdHocWindow(input) {
+	const window = input.lastMs !== void 0 ? {
+		from: input.nowMs - input.lastMs,
+		to: input.nowMs
+	} : {
+		from: input.fromMs ?? input.oldestMs,
+		to: input.toMs ?? input.nowMs
+	};
+	if (window.from >= window.to) throw new Error(`adhoc window is empty: from (${msToIso(window.from)}) must be strictly before to (${msToIso(window.to)}).`);
+	return window;
+}
+function buildAdHocSlice(tables, window) {
+	const slice = {};
+	for (const table of tables) slice[table] = {
+		from: window.from,
+		to: window.to
+	};
+	return slice;
+}
 const SYNTHESIZERS_DIR_RELATIVE = ".agents/synthesizers";
 const SAFE_ENGINE_NAME_PATTERN = /^[A-Za-z0-9._-]+$/u;
 function assertSafeEngineName(name) {
@@ -29674,25 +29712,6 @@ function formatError(error) {
 	if (error instanceof Error) return error.message;
 	return String(error);
 }
-function msToIso(ms) {
-	return new Date(ms).toISOString();
-}
-const isoMsSchema = string().transform((value, ctx) => {
-	const ms = Date.parse(value);
-	if (Number.isNaN(ms)) {
-		ctx.addIssue({
-			code: "custom",
-			message: "must be an ISO-8601 timestamp"
-		});
-		return NEVER;
-	}
-	return ms;
-});
-function isoToMs(iso, label) {
-	const result = isoMsSchema.safeParse(iso);
-	if (!result.success) throw new Error(`${label} is not a valid ISO-8601 timestamp: ${iso}`);
-	return result.data;
-}
 const cursorFileSchema = strictObject({
 	floors: record(string(), isoMsSchema),
 	frontier: isoMsSchema
@@ -29718,12 +29737,12 @@ async function writeCursor(rootDir, synthesizerName, cursor) {
 }
 const ENGINE_CONFIG_FILE_NAME = "engine.json";
 const nonEmptyStringSchema$1 = string().trim().min(1);
-const DURATION_UNIT_MS = {
+const DURATION_UNIT_MS$1 = {
 	h: 36e5,
 	m: 6e4,
 	s: 1e3
 };
-const durationMsSchema = string().transform((value, ctx) => {
+const durationMsSchema$1 = string().transform((value, ctx) => {
 	const match = /^(\d+)([hms])$/.exec(value);
 	if (match === null) {
 		ctx.addIssue({
@@ -29733,7 +29752,7 @@ const durationMsSchema = string().transform((value, ctx) => {
 		return NEVER;
 	}
 	const [, amount, unit] = match;
-	return Number(amount) * DURATION_UNIT_MS[unit];
+	return Number(amount) * DURATION_UNIT_MS$1[unit];
 });
 const microsandboxConfigSchema = record(string(), unknown()).superRefine((config, ctx) => {
 	if ("bindMounts" in config) ctx.addIssue({
@@ -29743,11 +29762,11 @@ const microsandboxConfigSchema = record(string(), unknown()).superRefine((config
 	});
 }).optional();
 const engineConfigSchema = strictObject({
-	maxSliceSize: durationMsSchema.optional(),
+	maxSliceSize: durationMsSchema$1.optional(),
 	microsandbox: microsandboxConfigSchema,
 	oldestConsideredPoint: isoMsSchema.optional(),
 	synthesizerImage: nonEmptyStringSchema$1.optional(),
-	tick: durationMsSchema.optional()
+	tick: durationMsSchema$1.optional()
 });
 function mergeEngineConfig(...inputs) {
 	return applyDefaults(Object.assign({}, ...inputs.map((input) => stripUndefined(input))));
@@ -29778,7 +29797,7 @@ function validate(raw, sourcePath) {
 }
 function applyDefaults(input) {
 	return {
-		synthesizerImage: input.synthesizerImage ?? "ghcr.io/usecontextlayer/ctx-sandbox:0.4.11",
+		synthesizerImage: input.synthesizerImage ?? "ghcr.io/usecontextlayer/ctx-sandbox:0.4.13",
 		...input.microsandbox !== void 0 ? { microsandbox: input.microsandbox } : {},
 		...input.oldestConsideredPoint !== void 0 ? { oldestConsideredPoint: input.oldestConsideredPoint } : {},
 		maxSliceSize: input.maxSliceSize ?? 864e5,
@@ -29796,14 +29815,12 @@ function formatZodError$1(error) {
 }
 function gatePasses(input) {
 	if (input.syncHorizon === null) return false;
-	if (input.mode === "manual") return input.frontier < input.syncHorizon;
 	return input.syncHorizon - input.frontier >= input.tick;
 }
 function planLoopPass(input) {
 	const horizon = input.syncHorizon;
 	const horizonDue = horizon === null ? [] : input.synthesizers.filter((synthesizer) => gatePasses({
 		frontier: synthesizer.frontier,
-		mode: "loop",
 		syncHorizon: horizon,
 		tick: input.tick
 	}));
@@ -30232,9 +30249,9 @@ function dirtyWorkingTreeIssue(paths) {
 	};
 }
 const runTriggerSchema = _enum([
+	"adhoc",
 	"backfill",
-	"daemon",
-	"manual"
+	"daemon"
 ]);
 _enum([
 	"success",
@@ -30484,6 +30501,14 @@ function formatCombinedRepairError(repo, branch, tree) {
 		"Operator must inspect and choose the order manually."
 	].join("\n");
 }
+function renderSliceJson(slice) {
+	const windows = {};
+	for (const [table, window] of Object.entries(slice)) windows[table] = {
+		from: msToIso(window.from),
+		to: msToIso(window.to)
+	};
+	return `${JSON.stringify(windows, null, "	")}\n`;
+}
 const synthesizerSpecFrontmatterSchema = strictObject({
 	description: string().optional(),
 	name: string().trim().min(1)
@@ -30800,15 +30825,16 @@ function buildSandboxFilesystemPlan(input) {
 	const guestWorkdir = workspaceGuestPath(rootDir);
 	const bindMounts = [{
 		guestPath: outputGuestPath(rootDir),
-		hostPath: path.join(rootDir, "output"),
+		hostPath: input.outputHostDir ?? path.join(rootDir, "output"),
 		hostPathBehavior: "createDir",
 		mode: "rw"
-	}, {
+	}];
+	if (input.mountTranscript ?? true) bindMounts.push({
 		guestPath: CLAUDE_PROJECTS_GUEST_PATH,
 		hostPath: claudeProjectsDirPath(rootDir),
 		hostPathBehavior: "createDir",
 		mode: "rw"
-	}];
+	});
 	const textPatches = [
 		{
 			content: input.claudeMaterial.claudeJson,
@@ -31036,9 +31062,11 @@ async function executeSynthesizerRun(input) {
 			runId: input.runId,
 			sliceJson: input.sliceJson,
 			synthesizer: input.synthesizer,
-			synthesizerImage: input.synthesizerImage
+			synthesizerImage: input.synthesizerImage,
+			...input.outputHostDir !== void 0 && { outputHostDir: input.outputHostDir },
+			...input.mountTranscript !== void 0 && { mountTranscript: input.mountTranscript }
 		});
-		const result = await input.executor.run(executorInput);
+		const result = await input.executor.run(executorInput, input.hooks);
 		const completedAtMs = now().getTime();
 		const durationMs = Math.max(0, completedAtMs - startedAtMs);
 		const status = classifyOutcome(result.exitCode, result.observation);
@@ -31087,7 +31115,9 @@ function buildExecutorInput(input) {
 		sandboxName: buildSandboxName(input.synthesizer.name, input.runId),
 		sliceJson: input.sliceJson,
 		synthesizerBody: input.synthesizer.body,
-		synthesizerName: input.synthesizer.name
+		synthesizerName: input.synthesizer.name,
+		...input.outputHostDir !== void 0 && { outputHostDir: input.outputHostDir },
+		...input.mountTranscript !== void 0 && { mountTranscript: input.mountTranscript }
 	};
 }
 function buildContextEngineEnv(input) {
@@ -31167,14 +31197,6 @@ function reconcileCursor(input) {
 		frontier: input.prevCursor.frontier
 	};
 }
-function renderSliceJson(slice) {
-	const windows = {};
-	for (const [table, window] of Object.entries(slice)) windows[table] = {
-		from: msToIso(window.from),
-		to: msToIso(window.to)
-	};
-	return `${JSON.stringify(windows, null, "	")}\n`;
-}
 const DEFAULT_OLDEST_LOOKBACK_MS = 720 * 60 * 60 * 1e3;
 function resolveOldest(config, beginMs) {
 	return config.oldestConsideredPoint ?? beginMs - DEFAULT_OLDEST_LOOKBACK_MS;
@@ -31195,14 +31217,7 @@ async function openSynthesizerTransaction(input) {
 		trigger: input.trigger
 	});
 	await writeRunRecord(runDir, startingRecord);
-	const watermark = await input.watermarkCapture({
-		rootDir: input.repo.rootDir,
-		runDir,
-		runId,
-		startedAt,
-		synthesizer: input.synthesizer,
-		trigger: input.trigger
-	});
+	const watermark = await input.watermarkCapture();
 	const persistedCursor = await readCursor(input.repo.rootDir, input.synthesizer.name);
 	const planConfig = {
 		maxSliceSize: input.config.maxSliceSize,
@@ -31372,26 +31387,38 @@ var Engine = class {
 			this.daemonRunning = false;
 		}
 	}
-	async runOnce(synthesizerName) {
-		await this.prepareSynthesizerRun(synthesizerName);
+	async runAdHoc(input) {
+		const synthesizer = await this.ensureSynthesizerLoaded(input.synthesizerName);
 		const config = this.requireConfig();
-		const syncHorizon = await this.syncHorizonCapture();
-		const frontier = (await readCursor(this.repo.rootDir, synthesizerName))?.frontier ?? resolveOldest(config, this.nowDate().getTime());
-		if (syncHorizon === null || !gatePasses({
-			frontier,
-			mode: "manual",
-			syncHorizon,
-			tick: config.tick
-		})) return { kind: "caught_up" };
-		const { record } = await this.runSynthesizerTransaction({
-			syncHorizon,
-			synthesizerName,
-			trigger: "manual"
+		const begin = this.nowDate();
+		const nowMs = begin.getTime();
+		const window = resolveAdHocWindow({
+			nowMs,
+			oldestMs: resolveOldest(config, nowMs),
+			...input.fromMs !== void 0 && { fromMs: input.fromMs },
+			...input.toMs !== void 0 && { toMs: input.toMs },
+			...input.lastMs !== void 0 && { lastMs: input.lastMs }
 		});
-		return {
-			kind: "ran",
-			record
-		};
+		const watermark = await this.watermarkCapture();
+		const sliceJson = renderSliceJson(buildAdHocSlice(Object.keys(watermark), window));
+		const runId = assertSafeEngineName((this.runIdFactory ?? v7)());
+		return (await executeSynthesizerRun({
+			databaseUrl: this.databaseUrl,
+			executor: this.executor,
+			logger: this.logger,
+			mountTranscript: false,
+			outputHostDir: input.outputDir,
+			rootDir: this.repo.rootDir,
+			runId,
+			sliceJson,
+			startedAt: begin.toISOString(),
+			synthesizer,
+			synthesizerImage: config.synthesizerImage,
+			trigger: "adhoc",
+			...config.microsandbox !== void 0 && { microsandboxConfig: config.microsandbox },
+			...this.now !== void 0 && { now: this.now },
+			...input.hooks !== void 0 && { hooks: input.hooks }
+		})).outcome;
 	}
 	async backfill(synthesizerName, options = {}) {
 		await this.prepareSynthesizerRun(synthesizerName);
@@ -31494,9 +31521,14 @@ var Engine = class {
 	async prepareSynthesizerRun(synthesizerName) {
 		const report = await runRootPreflight(this.repo);
 		if (!report.ready) throw new Error(formatPreflightFailure(this.repo.rootDir, report.issues));
+		await this.ensureSynthesizerLoaded(synthesizerName);
+	}
+	async ensureSynthesizerLoaded(synthesizerName) {
 		await this.ensureLoaded();
 		await this.refreshSynthesizers();
-		if (!this.synthesizers.has(synthesizerName)) throw new Error(`Unknown synthesizer '${synthesizerName}'.`);
+		const synthesizer = this.synthesizers.get(synthesizerName);
+		if (!synthesizer) throw new Error(`Unknown synthesizer '${synthesizerName}'.`);
+		return synthesizer;
 	}
 	async runSynthesizerTransaction(request) {
 		const releaseLock = await acquireTransactionLock(this.repo.rootDir);
@@ -31761,6 +31793,7 @@ async function drainExecStream(handle, options) {
 		if (settled.kind === "stderr") options.onStderr(settled.data);
 		else if (settled.kind === "stdout") {
 			observer.feed(settled.data);
+			options.onStdout(settled.data);
 			if (resultSeenAt === void 0 && observer.resultSeen) resultSeenAt = lastEventAt;
 		} else if (settled.kind === "exited") return {
 			exitCode: settled.code,
@@ -31770,7 +31803,7 @@ async function drainExecStream(handle, options) {
 	}
 }
 var MicrosandboxClaudeExecutor = class {
-	async run(input) {
+	async run(input, hooks) {
 		const microsandbox = await import("microsandbox");
 		const runPlan = buildMicrosandboxClaudeRunPlan(input);
 		const stderrParts = [];
@@ -31789,7 +31822,9 @@ var MicrosandboxClaudeExecutor = class {
 				guestEnv: runPlan.microsandboxConfig.env,
 				rootDir: input.rootDir,
 				sliceJson: input.sliceJson,
-				synthesizerBody: input.synthesizerBody
+				synthesizerBody: input.synthesizerBody,
+				...input.outputHostDir !== void 0 && { outputHostDir: input.outputHostDir },
+				...input.mountTranscript !== void 0 && { mountTranscript: input.mountTranscript }
 			});
 			await ensureHostFilesystemReady(fsPlan);
 			let builder = microsandbox.Sandbox.builder(runPlan.sandboxName).image(runPlan.image).memory(GUEST_MEMORY_MIB).replace();
@@ -31798,14 +31833,23 @@ var MicrosandboxClaudeExecutor = class {
 			sandbox = await builder.create();
 			const [cmd, ...args] = runPlan.command;
 			const stderrDecoder = new TextDecoder("utf-8", { fatal: false });
+			const stdoutDecoder = new TextDecoder("utf-8", { fatal: false });
 			try {
 				const drained = await drainExecStream(await sandbox.execStreamWith(cmd, (e) => e.args(args)), {
 					inactivityMs: EXEC_INACTIVITY_TIMEOUT_MS,
 					maxDurationMs: EXEC_MAX_DURATION_MS,
-					onStderr: (data) => stderrParts.push(stderrDecoder.decode(data, { stream: true })),
+					onStderr: (data) => {
+						const text = stderrDecoder.decode(data, { stream: true });
+						stderrParts.push(text);
+						hooks?.onStderr?.(text);
+					},
+					onStdout: (data) => {
+						if (hooks?.onStdout) hooks.onStdout(stdoutDecoder.decode(data, { stream: true }));
+					},
 					resultGraceMs: EXEC_RESULT_GRACE_MS
 				});
 				stderrParts.push(stderrDecoder.decode());
+				hooks?.onStdout?.(stdoutDecoder.decode());
 				observation = drained.observation;
 				if (drained.kind === "exited") exitCode = drained.exitCode;
 				else if (drained.kind === "result_no_exit") {
@@ -32151,6 +32195,62 @@ async function runEngineLogsCommand(synthesizerName, options, paths) {
 	}));
 }
 
+//#endregion
+//#region commands/adhoc.ts
+const DURATION_UNIT_MS = {
+	d: 864e5,
+	h: 36e5,
+	m: 6e4,
+	s: 1e3
+};
+const durationMsSchema = string().transform((value, ctx) => {
+	const match = /^(\d+)(d|h|m|s)$/.exec(value);
+	if (match === null) {
+		ctx.addIssue({
+			code: "custom",
+			message: "must be a duration like \"7d\", \"12h\", \"30m\", or \"45s\""
+		});
+		return NEVER;
+	}
+	const [, amount, unit] = match;
+	return Number(amount) * DURATION_UNIT_MS[unit];
+});
+const adHocWindowSchema = object({
+	from: isoMsSchema.optional(),
+	last: durationMsSchema.optional(),
+	to: isoMsSchema.optional()
+}).refine((window) => window.last !== void 0 !== (window.from !== void 0 || window.to !== void 0), { message: "provide --last, or at least one of --from/--to (not both)" });
+async function runAdHocCommand(input) {
+	const window = adHocWindowSchema.parse({
+		...input.from !== void 0 && { from: input.from },
+		...input.to !== void 0 && { to: input.to },
+		...input.last !== void 0 && { last: input.last }
+	});
+	const engine = buildEngine({
+		databaseUrl: resolveDatabaseUrl({ cliValue: input.databaseUrl }),
+		paths: input.paths
+	});
+	const outputDir = resolve(input.out);
+	const outcome = await engine.runAdHoc({
+		hooks: {
+			onStderr: (chunk) => process.stderr.write(chunk),
+			onStdout: (chunk) => process.stdout.write(chunk)
+		},
+		outputDir,
+		synthesizerName: input.synthesizerName,
+		...window.from !== void 0 && { fromMs: window.from },
+		...window.to !== void 0 && { toMs: window.to },
+		...window.last !== void 0 && { lastMs: window.last }
+	});
+	process.stderr.write(`${formatJsonOutput({
+		durationMs: outcome.durationMs,
+		exitCode: outcome.exitCode,
+		out: outputDir,
+		status: outcome.status
+	})}\n`);
+	if (outcome.status !== "success") process.exitCode = 1;
+}
+
 //#endregion
 //#region commands/backfill.ts
 async function runBackfillCommand(input) {
@@ -32205,21 +32305,6 @@ async function runResetCommand(input) {
 	process.stdout.write(`${formatJsonOutput(result)}\n`);
 }
 
-//#endregion
-//#region commands/run.ts
-async function runRunCommand(input) {
-	const outcome = await buildEngine({
-		databaseUrl: resolveDatabaseUrl({ cliValue: input.databaseUrl }),
-		paths: input.paths
-	}).runOnce(input.synthesizerName);
-	if (outcome.kind === "caught_up") {
-		process.stdout.write(`${formatJsonOutput({ status: "caught_up" })}\n`);
-		return;
-	}
-	process.stdout.write(`${formatJsonOutput(outcome.record)}\n`);
-	if (outcome.record.status !== "success") process.exitCode = 1;
-}
-
 //#endregion
 //#region commands/start.ts
 async function runStartCommand(input) {
@@ -32319,11 +32404,15 @@ function createProgram() {
 			yes: options.yes ?? false
 		});
 	});
-	program.command("run").argument("<synthesizer>", "Synthesizer name").option("--database-url <url>", "Postgres URL of the ContextBase database the synthesizer reads from. Falls back to CTXB_DATABASE_URL.").description("Run a single synthesizer once. Prints caught_up and exits zero when there is no new synced ground; exits non-zero on any non-success run (failed, timed-out, or rate-limited).").action(async function(synthesizerName, options) {
-		await runRunCommand({
+	program.command("adhoc").argument("<synthesizer>", "Synthesizer name").option("--from <iso>", "Window start (ISO-8601, exclusive). Defaults to the engine's oldestConsideredPoint when omitted.").option("--to <iso>", "Window end (ISO-8601, inclusive). Defaults to now when omitted.").option("--last <duration>", "Relative window ending now, e.g. \"7d\", \"12h\", \"30m\". Mutually exclusive with --from/--to.").requiredOption("--out <dir>", "Directory the synthesized output is written to. Used exactly as-is (created if missing); the synthesizer reads its current contents as prior output.").option("--database-url <url>", "Postgres URL of the ContextBase database the synthesizer reads from. Falls back to CTXB_DATABASE_URL.").description("Ephemeral authoring run: run a synthesizer once over an explicit window into --out, reading your live (uncommitted) synthesizer.md and output/types. Touches nothing durable — no preflight, no sync horizon, no cursor, no commit, no push. Streams the run to stdout; saves no transcript. Exits non-zero on a non-success run.").action(async function(synthesizerName, options) {
+		await runAdHocCommand({
 			databaseUrl: options.databaseUrl,
+			from: options.from,
+			last: options.last,
+			out: options.out,
 			paths: resolveRuntimePaths(this),
-			synthesizerName
+			synthesizerName,
+			to: options.to
 		});
 	});
 	program.command("backfill").argument("<synthesizer>", "Synthesizer name").option("--database-url <url>", "Postgres URL of the ContextBase database the synthesizer reads from. Falls back to CTXB_DATABASE_URL.").description("Walk a synthesizer's cursor forward slice-by-slice until it catches up to the sync horizon. The same loop the daemon runs, without the sleep. Streams each slice's run record; prints a summary; exits non-zero if a slice fails or the usage window is rate-limited.").action(async function(synthesizerName, options) {
@@ -32362,4 +32451,4 @@ runCli().catch((error) => {
 //#endregion
 export { createProgram, resolveRepoContext, resolveRuntimePaths, runCli };
 //# sourceMappingURL=cli.mjs.map
-//# debugId=7487993d-7bca-5e7a-92f4-fc03dc11a776
+//# debugId=ef06741d-8451-516d-a05b-dd7da1f526a8