acpx 0.8.0 → 0.10.0

package/dist/cli.js

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
-import { a as runSessionQueueOwner, c as buildQueueOwnerArgOverride, h as __exportAll, l as flushPerfMetricsCapture, n as getTextErrorRemediationHints, p as probeQueueOwnerHealth, t as createOutputFormatter, u as installPerfMetricsCapture } from "./output-BL9XRWzS.js";
-import { At as EXIT_CODES, F as findSession, I as findSessionByDirectoryWalk, P as findGitRepositoryRoot, Pt as OUTPUT_FORMATS, St as exitCodeForOutputErrorCode, Tt as normalizeOutputError, bt as normalizeAgentName, ct as PromptInputValidationError, dt as parsePromptSource, mt as InterruptedError, pt as textPrompt, st as normalizeRuntimeSessionId, ut as mergePromptSourceWithText, vt as DEFAULT_AGENT_NAME, yt as listBuiltInAgents } from "./live-checkpoint-B9ctAuqV.js";
-import { _ as resolveOutputPolicy, b as loadPermissionPolicySpec, c as parseHistoryLimit, d as parseOutputFormat$1, f as parsePruneBeforeDate, g as resolveGlobalFlags, h as resolveAgentInvocation, i as addSessionOption, l as parseMaxTurns, m as parseTtlSeconds, n as addPromptInputOption, o as parseAllowedTools, p as parseSessionName, r as addSessionNameOption, s as parseDaysOlderThan, t as addGlobalFlags, u as parseNonEmptyValue, v as resolvePermissionMode, y as resolveSessionNameFromFlags } from "./flags-D706STfk.js";
+import { a as runSessionQueueOwner, c as buildQueueOwnerArgOverride, g as __exportAll, h as isProcessAlive, l as flushPerfMetricsCapture, n as getTextErrorRemediationHints, p as probeQueueOwnerHealth, t as createOutputFormatter, u as installPerfMetricsCapture } from "./output-Di77Yugq.js";
+import { $ as defaultSessionEventLog, A as findGitRepositoryRoot, At as EXIT_CODES, I as normalizeName, M as findSessionByDirectoryWalk, P as listSessions, Pt as OUTPUT_FORMATS, Rt as AcpxOperationalError, St as exitCodeForOutputErrorCode, Tt as normalizeOutputError, X as serializeSessionRecordForDisk, Y as parseSessionRecord, Z as normalizeRuntimeSessionId, at as isAcpJsonRpcMessage, bt as normalizeAgentName$1, ct as PromptInputValidationError, dt as parsePromptSource, j as findSession, mt as InterruptedError, nt as sessionEventLockPath, pt as textPrompt, rt as sessionEventSegmentPath, tt as sessionEventActivePath, ut as mergePromptSourceWithText, vt as DEFAULT_AGENT_NAME, yt as listBuiltInAgents, z as writeSessionRecord, zt as AgentSpawnError } from "./live-checkpoint-CuFft_Nd.js";
+import { _ as resolveOutputPolicy, b as loadPermissionPolicySpec, c as parseHistoryLimit, d as parseOutputFormat$1, f as parsePruneBeforeDate, g as resolveGlobalFlags, h as resolveAgentInvocation, i as addSessionOption, l as parseMaxTurns, m as parseTtlSeconds, n as addPromptInputOption, o as parseAllowedTools, p as parseSessionName, r as addSessionNameOption, s as parseDaysOlderThan, t as addGlobalFlags, u as parseNonEmptyValue, v as resolvePermissionMode, y as resolveSessionNameFromFlags } from "./flags--2oX_ubW.js";
 import { readFileSync, realpathSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import path from "node:path";
-import { Command, CommanderError, InvalidArgumentError } from "commander";
+import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
 import fs$1 from "node:fs/promises";
 import os from "node:os";
+import { randomUUID } from "node:crypto";
+import { ZodError, z } from "zod";
 //#region src/cli-public.ts
 function configurePublicCli(options) {
 	const builtInAgents = options.listBuiltInAgents(options.config.agents);
@@ -34,7 +36,7 @@ Examples:
   acpx codex exec "what does this repo do"
   acpx codex cancel
   acpx codex set-mode plan
-  acpx codex set thought_level high
+  acpx codex set model 'gpt-5.2[high]'
   acpx codex -s backend "fix the API"
   acpx codex sessions
   acpx codex sessions new --name backend
@@ -49,9 +51,321 @@ Examples:
 }
 //#endregion
 //#region src/acp/codex-compat.ts
-function isCodexInvocation(agentName, agentCommand) {
-	if (agentName === "codex") return true;
-	return /\bcodex-acp\b/u.test(agentCommand);
+function isLegacyZedCodexAcpInvocation(agentCommand) {
+	return /@zed-industries\/codex-acp\b/u.test(agentCommand);
+}
+//#endregion
+//#region src/session/export.ts
+var SessionExportError = class extends AcpxOperationalError {
+	code;
+	exitCode = 2;
+	constructor(message, code) {
+		super(message, {
+			outputCode: "USAGE",
+			detailCode: code,
+			origin: "cli"
+		});
+		this.code = code;
+	}
+};
+function sessionLookupError(message, code) {
+	return new SessionExportError(message, code);
+}
+async function loadSessionRecord(sessionLookup) {
+	const cwd = path.resolve(sessionLookup.cwd ?? process.cwd());
+	const name = normalizeName(sessionLookup.name);
+	if (sessionLookup.agentCommand) {
+		const active = await findSession({
+			agentCommand: sessionLookup.agentCommand,
+			cwd,
+			name
+		});
+		if (active) return active;
+		return (await listSessions()).find((session) => {
+			if (session.agentCommand !== sessionLookup.agentCommand || session.cwd !== cwd) return false;
+			if (name == null) return session.name == null;
+			return session.name === name;
+		});
+	}
+	const matches = (await listSessions()).filter((session) => {
+		if (session.cwd !== cwd) return false;
+		if (name == null) return session.name == null;
+		return session.name === name;
+	});
+	if (matches.length > 1) throw sessionLookupError("multiple sessions match export lookup", "ambiguous-session");
+	return matches[0];
+}
+function parseEventLockPayload(raw) {
+	try {
+		const parsed = JSON.parse(raw);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+		const record = parsed;
+		return { pid: typeof record.pid === "number" ? record.pid : void 0 };
+	} catch {
+		return {};
+	}
+}
+async function hasLiveEventLock(recordId) {
+	try {
+		return isProcessAlive(parseEventLockPayload(await fs$1.readFile(sessionEventLockPath(recordId), "utf8")).pid);
+	} catch (error) {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+async function isSessionActive(record) {
+	if (record.closed) return false;
+	return isProcessAlive(record.pid) || await hasLiveEventLock(record.acpxRecordId);
+}
+async function readHistoryFile(filePath) {
+	const payload = await fs$1.readFile(filePath, "utf8").catch((error) => {
+		if (error.code === "ENOENT") return "";
+		throw error;
+	});
+	const history = [];
+	for (const line of payload.split("\n").filter((entry) => entry.trim().length > 0)) try {
+		const parsed = JSON.parse(line);
+		if (isAcpJsonRpcMessage(parsed)) history.push(parsed);
+	} catch {}
+	return history;
+}
+async function readSessionHistory(record) {
+	const history = [];
+	const maxSegments = Number.isInteger(record.eventLog.max_segments) ? record.eventLog.max_segments : 0;
+	for (let segment = maxSegments; segment >= 1; segment -= 1) history.push(...await readHistoryFile(sessionEventSegmentPath(record.acpxRecordId, segment)));
+	history.push(...await readHistoryFile(sessionEventActivePath(record.acpxRecordId)));
+	return history;
+}
+function cwdRelativeToHome(cwd, home) {
+	const relative = path.relative(home, cwd);
+	if (relative.length === 0) return ".";
+	if (relative.length > 0 && !relative.startsWith("..") && !path.isAbsolute(relative)) return relative;
+	return cwd;
+}
+function serializeSessionRecordForArchive(record, cwdRelative) {
+	const state = serializeSessionRecordForDisk(record);
+	state.cwd = cwdRelative;
+	if (state.event_log && typeof state.event_log === "object" && !Array.isArray(state.event_log)) state.event_log = {
+		...state.event_log,
+		active_path: ".stream.ndjson"
+	};
+	return state;
+}
+async function exportSession(sessionLookup, outputPath) {
+	const record = await loadSessionRecord(sessionLookup);
+	if (!record) throw sessionLookupError("session not found", "not-found");
+	if (await isSessionActive(record)) throw sessionLookupError("session is currently locked by a running queue owner; close it first with `acpx sessions close`", "session-locked");
+	const home = os.homedir();
+	const cwdRelative = cwdRelativeToHome(record.cwd, home);
+	const exported = {
+		format_version: 1,
+		exported_at: (/* @__PURE__ */ new Date()).toISOString(),
+		exported_by: "acpx",
+		session: {
+			record_id: record.acpxRecordId,
+			name: record.name ?? null,
+			agent: record.agentCommand,
+			agent_name: normalizeAgentName(sessionLookup.agentName),
+			cwd_relative: cwdRelative,
+			cwd_original: cwdRelative,
+			created_at: record.createdAt,
+			updated_at: record.lastUsedAt,
+			state: serializeSessionRecordForArchive(record, cwdRelative)
+		},
+		history: await readSessionHistory(record)
+	};
+	await fs$1.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+	await fs$1.writeFile(outputPath, `${JSON.stringify(exported, null, 2)}\n`, "utf8");
+}
+function normalizeAgentName(agentName) {
+	const normalized = agentName?.trim().toLowerCase();
+	if (!normalized || normalized.length === 0) return;
+	return normalized === "factory-droid" || normalized === "factorydroid" ? "droid" : normalized;
+}
+//#endregion
+//#region src/session/import.ts
+const SUPPORTED_FORMAT_VERSION = 1;
+const exportedSessionSchema = z.object({
+	format_version: z.literal(SUPPORTED_FORMAT_VERSION),
+	exported_at: z.string(),
+	exported_by: z.string(),
+	session: z.object({
+		record_id: z.string(),
+		name: z.string().nullable(),
+		agent: z.string(),
+		agent_name: z.string().optional(),
+		cwd_relative: z.string(),
+		cwd_original: z.string().optional(),
+		cwd_absolute_original: z.string().optional(),
+		created_at: z.string(),
+		updated_at: z.string(),
+		state: z.unknown()
+	}),
+	history: z.array(z.unknown())
+});
+var SessionImportError = class extends AcpxOperationalError {
+	code;
+	exitCode = 2;
+	constructor(message, code) {
+		super(message, {
+			outputCode: "USAGE",
+			detailCode: code,
+			origin: "cli"
+		});
+		this.code = code;
+	}
+};
+function importError(message, code) {
+	return new SessionImportError(message, code);
+}
+function parseArchiveJson(raw) {
+	try {
+		return JSON.parse(raw);
+	} catch (error) {
+		throw importError(`Invalid session export archive JSON: ${error instanceof Error ? error.message : String(error)}`, "invalid-archive");
+	}
+}
+function assertSupportedFormatVersion(parsed) {
+	const record = parsed && typeof parsed === "object" ? parsed : {};
+	if (record.format_version !== SUPPORTED_FORMAT_VERSION) throw importError(`Unsupported session export format_version ${String(record.format_version)}; supported version is ${SUPPORTED_FORMAT_VERSION}`, "unsupported-format-version");
+}
+function parseArchive(raw) {
+	const parsed = parseArchiveJson(raw);
+	assertSupportedFormatVersion(parsed);
+	try {
+		return exportedSessionSchema.parse(parsed);
+	} catch (error) {
+		if (error instanceof ZodError) throw importError(`Invalid session export archive: ${error.issues[0]?.message}`, "invalid-archive");
+		throw error;
+	}
+}
+async function generateRecordId(sessionsDir) {
+	for (;;) {
+		const recordId = randomUUID();
+		const filePath = path.join(sessionsDir, `${encodeURIComponent(recordId)}.json`);
+		try {
+			await fs$1.access(filePath);
+		} catch (error) {
+			if (error.code === "ENOENT") return recordId;
+			throw error;
+		}
+	}
+}
+function resolveImportedCwd(cwdRelative, newCwd) {
+	if (newCwd) return path.resolve(newCwd);
+	if (path.isAbsolute(cwdRelative)) return cwdRelative;
+	return path.join(os.homedir(), cwdRelative);
+}
+function resolveImportedName(parsed, requestedName) {
+	return requestedName ?? parsed.session.name ?? void 0;
+}
+function assertExpectedAgentCommand(parsed, sourceRecord, options) {
+	const expectedAgentCommand = options.expectedAgentCommand;
+	if (!expectedAgentCommand) return;
+	const expectedAgentName = normalizeAgentIdentity(options.expectedAgentName);
+	const archiveAgentName = normalizeAgentIdentity(parsed.session.agent_name);
+	const archiveCommandMatches = agentCommandMatchesExpected(parsed.session.agent, expectedAgentCommand, expectedAgentName);
+	const stateCommandMatches = agentCommandMatchesExpected(sourceRecord.agentCommand, expectedAgentCommand, expectedAgentName);
+	if (archiveCommandMatches && stateCommandMatches && archiveAgentNameMatches({
+		archiveAgentName,
+		expectedAgentName,
+		archiveCommand: parsed.session.agent,
+		stateCommand: sourceRecord.agentCommand,
+		expectedAgentCommand
+	})) {
+		sourceRecord.agentCommand = expectedAgentCommand;
+		return;
+	}
+	throw importError("Session export archive agent does not match the requested agent", "agent-mismatch");
+}
+function archiveAgentNameMatches(params) {
+	if (params.archiveCommand === params.expectedAgentCommand && params.stateCommand === params.expectedAgentCommand) return true;
+	return params.archiveAgentName == null || params.expectedAgentName == null || params.archiveAgentName === params.expectedAgentName;
+}
+function normalizeAgentIdentity(agentName) {
+	const normalized = agentName?.trim().toLowerCase();
+	if (!normalized || normalized.length === 0) return;
+	return normalized === "factory-droid" || normalized === "factorydroid" ? "droid" : normalized;
+}
+function agentCommandMatchesExpected(archivedCommand, expectedAgentCommand, expectedAgentName) {
+	if (archivedCommand === expectedAgentCommand) return true;
+	return expectedAgentName ? commandLooksLikeBuiltInAgent(archivedCommand, expectedAgentName) : false;
+}
+function commandLooksLikeBuiltInAgent(command, agentName) {
+	const normalized = command.trim();
+	switch (agentName) {
+		case "pi": return /(?:^|\s)pi-acp(?:@|\s|$)/.test(normalized);
+		case "codex": return /(?:^|\s)@agentclientprotocol\/codex-acp(?:@|\s|$)/.test(normalized);
+		case "claude": return /(?:^|\s)@agentclientprotocol\/claude-agent-acp(?:@|\s|$)/.test(normalized);
+		default: return false;
+	}
+}
+async function assertDestinationScopeAvailable(record) {
+	if (!await findSession({
+		agentCommand: record.agentCommand,
+		cwd: record.cwd,
+		name: record.name
+	})) return;
+	throw importError("A session already exists for the import destination scope; pass --name or --cwd to import a separate copy", "session-scope-exists");
+}
+async function assertProviderSessionAvailable(record) {
+	if (!(await listSessions()).find((session) => session.acpSessionId === record.acpSessionId)) return;
+	throw importError("A local session already uses this provider session id; prune or remove the existing record before importing this archive", "session-provider-exists");
+}
+function buildImportedRecord(parsed, sourceRecord, options) {
+	const eventLog = {
+		...defaultSessionEventLog(options.newRecordId),
+		max_segment_bytes: sourceRecord.eventLog.max_segment_bytes,
+		max_segments: sourceRecord.eventLog.max_segments,
+		segment_count: parsed.history.length > 0 ? 1 : sourceRecord.eventLog.segment_count
+	};
+	return {
+		...sourceRecord,
+		acpxRecordId: options.newRecordId,
+		cwd: options.cwd,
+		name: resolveImportedName(parsed, options.name),
+		closed: false,
+		closedAt: void 0,
+		pid: void 0,
+		agentStartedAt: void 0,
+		lastAgentExitCode: void 0,
+		lastAgentExitSignal: void 0,
+		lastAgentExitAt: void 0,
+		lastAgentDisconnectReason: void 0,
+		eventLog,
+		importedFrom: {
+			recordId: parsed.session.record_id,
+			cwdOriginal: parsed.session.cwd_original ?? parsed.session.cwd_relative,
+			exportedBy: parsed.exported_by,
+			exportedAt: parsed.exported_at
+		}
+	};
+}
+async function importSession(archivePath, options = {}) {
+	const parsed = parseArchive(await fs$1.readFile(archivePath, "utf8"));
+	const sourceRecord = parseSessionRecord(parsed.session.state);
+	if (!sourceRecord) throw importError("Invalid session export archive: session.state is not a session record", "invalid-archive");
+	assertExpectedAgentCommand(parsed, sourceRecord, options);
+	const sessionsDir = path.join(os.homedir(), ".acpx", "sessions");
+	await fs$1.mkdir(sessionsDir, { recursive: true });
+	const cwd = resolveImportedCwd(parsed.session.cwd_relative, options.newCwd);
+	const newRecordId = await generateRecordId(sessionsDir);
+	const newRecord = buildImportedRecord(parsed, sourceRecord, {
+		newRecordId,
+		cwd,
+		name: options.name
+	});
+	await assertDestinationScopeAvailable(newRecord);
+	await assertProviderSessionAvailable(newRecord);
+	await writeSessionRecord(newRecord);
+	if (parsed.history.length > 0) {
+		const history = parsed.history;
+		await fs$1.writeFile(sessionEventActivePath(newRecordId), `${history.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf8");
+	}
+	return {
+		record_id: newRecordId,
+		cwd
+	};
 }
 //#endregion
 //#region src/cli/output/json-output.ts
@@ -72,11 +386,11 @@ let sessionModulePromise;
 let outputModulePromise;
 let outputRenderModulePromise;
 function loadSessionModule() {
-	sessionModulePromise ??= import("./output-BL9XRWzS.js").then((n) => n.i);
+	sessionModulePromise ??= import("./output-Di77Yugq.js").then((n) => n.i);
 	return sessionModulePromise;
 }
 function loadOutputModule() {
-	outputModulePromise ??= import("./output-BL9XRWzS.js").then((n) => n.r);
+	outputModulePromise ??= import("./output-Di77Yugq.js").then((n) => n.r);
 	return outputModulePromise;
 }
 function loadOutputRenderModule() {
@@ -90,11 +404,7 @@ async function readPromptInputFromStdin() {
 }
 async function readPrompt(promptParts, filePath, cwd) {
 	try {
-		if (filePath) {
-			const prompt = mergePromptSourceWithText(filePath === "-" ? await readPromptInputFromStdin() : await fs$1.readFile(path.resolve(cwd, filePath), "utf8"), promptParts.join(" "));
-			if (prompt.length === 0) throw new InvalidArgumentError("Prompt from --file is empty");
-			return prompt;
-		}
+		if (filePath) return await readPromptFromFile(filePath, cwd, promptParts);
 		const joined = promptParts.join(" ").trim();
 		if (joined.length > 0) return textPrompt(joined);
 		if (process.stdin.isTTY) throw new InvalidArgumentError("Prompt is required (pass as argument, --file, or pipe via stdin)");
@@ -106,13 +416,18 @@ async function readPrompt(promptParts, filePath, cwd) {
 		throw error;
 	}
 }
+async function readPromptFromFile(filePath, cwd, promptParts) {
+	const prompt = mergePromptSourceWithText(filePath === "-" ? await readPromptInputFromStdin() : await fs$1.readFile(path.resolve(cwd, filePath), "utf8"), promptParts.join(" "));
+	if (prompt.length === 0) throw new InvalidArgumentError("Prompt from --file is empty");
+	return prompt;
+}
 function applyPermissionExitCode(result) {
 	const stats = result.permissionStats;
 	const deniedOrCancelled = stats.denied + stats.cancelled;
 	if (stats.requested > 0 && stats.approved === 0 && deniedOrCancelled > 0) process.exitCode = EXIT_CODES.PERMISSION_DENIED;
 }
 function resolveCompatibleConfigId(agent, configId) {
-	if (isCodexInvocation(agent.agentName, agent.agentCommand) && configId === "thought_level") return "reasoning_effort";
+	if (isLegacyZedCodexAcpInvocation(agent.agentCommand) && configId === "thought_level") return "reasoning_effort";
 	return configId;
 }
 function resolveRequestedOutputPolicy(globalFlags) {
@@ -154,6 +469,14 @@ function buildSessionStartOptions(params) {
 		sessionOptions: sessionOptionsFromGlobalFlags(params.globalFlags)
 	};
 }
+function resolveSessionListFilterCwd(flags, agentCwd) {
+	return flags.filterCwd ? path.resolve(agentCwd, flags.filterCwd) : void 0;
+}
+async function printLocalSessionsList(agentCommand, filterCwd, format) {
+	const [{ listSessionsForAgent }, { printSessionsByFormat }] = await Promise.all([loadSessionModule(), loadOutputRenderModule()]);
+	const sessions = await listSessionsForAgent(agentCommand);
+	printSessionsByFormat(filterCwd ? sessions.filter((session) => session.cwd === filterCwd) : sessions, format);
+}
 function missingScopedSessionMessage(agent, sessionName) {
 	return sessionName ? `No named session "${sessionName}" for cwd ${agent.cwd} and agent ${agent.agentName}` : `No cwd session for ${agent.cwd} and agent ${agent.agentName}`;
 }
@@ -227,7 +550,7 @@ async function handlePrompt(explicitAgentName, promptParts, flags, command, conf
 		return;
 	}
 	applyPermissionExitCode(result);
-	if (globalFlags.verbose && result.loadError) process.stderr.write(`[acpx] loadSession failed, started fresh session: ${result.loadError}\n`);
+	if (globalFlags.verbose && result.loadError) process.stderr.write(`[acpx] session reconnect failed, started fresh session: ${result.loadError}\n`);
 }
 async function handleExec(explicitAgentName, promptParts, flags, command, config) {
 	if (config.disableExec) {
@@ -356,7 +679,7 @@ async function handleSetMode(explicitAgentName, modeId, flags, command, config)
 		timeoutMs: globalFlags.timeout,
 		verbose: globalFlags.verbose
 	});
-	if (globalFlags.verbose && result.loadError) process.stderr.write(`[acpx] loadSession failed, started fresh session: ${result.loadError}\n`);
+	if (globalFlags.verbose && result.loadError) process.stderr.write(`[acpx] session reconnect failed, started fresh session: ${result.loadError}\n`);
 	printSetModeResultByFormat(modeId, result, globalFlags.format);
 }
 async function handleSetModel(explicitAgentName, modelId, flags, command, config) {
@@ -374,7 +697,7 @@ async function handleSetModel(explicitAgentName, modelId, flags, command, config
 		timeoutMs: globalFlags.timeout,
 		verbose: globalFlags.verbose
 	});
-	if (globalFlags.verbose && result.loadError) process.stderr.write(`[acpx] loadSession failed, started fresh session: ${result.loadError}\n`);
+	if (globalFlags.verbose && result.loadError) process.stderr.write(`[acpx] session reconnect failed, started fresh session: ${result.loadError}\n`);
 	printSetModelResultByFormat(modelId, result, globalFlags.format);
 }
 async function handleSetConfigOption(explicitAgentName, configId, value, flags, command, config) {
@@ -398,14 +721,50 @@ async function handleSetConfigOption(explicitAgentName, configId, value, flags,
 		timeoutMs: globalFlags.timeout,
 		verbose: globalFlags.verbose
 	});
-	if (globalFlags.verbose && result.loadError) process.stderr.write(`[acpx] loadSession failed, started fresh session: ${result.loadError}\n`);
+	if (globalFlags.verbose && result.loadError) process.stderr.write(`[acpx] session reconnect failed, started fresh session: ${result.loadError}\n`);
 	printSetConfigOptionResultByFormat(configId, value, result, globalFlags.format);
 }
-async function handleSessionsList(explicitAgentName, command, config) {
+async function tryListAgentSessions(agent, flags, globalFlags, config) {
+	const permissionMode = resolvePermissionMode(globalFlags, config.defaultPermissions);
+	const permissionPolicy = await resolvePermissionPolicyFromFlags(globalFlags);
+	const { listAgentSessions } = await loadSessionModule();
+	try {
+		return await listAgentSessions({
+			agentCommand: agent.agentCommand,
+			cwd: agent.cwd,
+			cursor: flags.cursor,
+			filterCwd: resolveSessionListFilterCwd(flags, agent.cwd),
+			mcpServers: config.mcpServers,
+			permissionMode,
+			nonInteractivePermissions: globalFlags.nonInteractivePermissions,
+			permissionPolicy,
+			authCredentials: config.auth,
+			authPolicy: globalFlags.authPolicy,
+			terminal: globalFlags.terminal,
+			timeoutMs: globalFlags.timeout,
+			verbose: globalFlags.verbose
+		});
+	} catch (error) {
+		if (error instanceof AgentSpawnError) return "spawn-failed";
+		throw error;
+	}
+}
+async function handleSessionsList(explicitAgentName, flags, command, config) {
 	const globalFlags = resolveGlobalFlags(command, config);
 	const agent = resolveAgentInvocation(explicitAgentName, globalFlags, config);
-	const [{ listSessionsForAgent }, { printSessionsByFormat }] = await Promise.all([loadSessionModule(), loadOutputRenderModule()]);
-	printSessionsByFormat(await listSessionsForAgent(agent.agentCommand), globalFlags.format);
+	const filterCwd = resolveSessionListFilterCwd(flags, agent.cwd);
+	if (flags.local) {
+		if (flags.cursor) throw new InvalidArgumentError("--cursor cannot be combined with --local");
+		await printLocalSessionsList(agent.agentCommand, filterCwd, globalFlags.format);
+		return;
+	}
+	const [result, { printAgentSessionsByFormat }] = await Promise.all([tryListAgentSessions(agent, flags, globalFlags, config), loadOutputRenderModule()]);
+	if (!result || result === "spawn-failed") {
+		if (result !== "spawn-failed" && (flags.cursor || flags.filterCwd)) throw new Error(`Agent command "${agent.agentCommand}" does not advertise sessionCapabilities.list; cannot use agent-side session/list filters`);
+		await printLocalSessionsList(agent.agentCommand, void 0, globalFlags.format);
+		return;
+	}
+	printAgentSessionsByFormat(result, globalFlags.format);
 }
 async function handleSessionsClose(explicitAgentName, sessionName, command, config) {
 	const globalFlags = resolveGlobalFlags(command, config);
@@ -470,6 +829,7 @@ function userContentToText(content) {
 	if ("Text" in content) return content.Text;
 	if ("Mention" in content) return content.Mention.content;
 	if ("Image" in content) return content.Image.source || "[image]";
+	if ("Audio" in content) return `[audio] ${content.Audio.mime_type || "audio"}`;
 	return "";
 }
 function agentContentToText(content) {
@@ -514,24 +874,32 @@ function printSessionDetailsByFormat(record, format) {
 		process.stdout.write(`${record.acpxRecordId}\n`);
 		return;
 	}
-	process.stdout.write(`id: ${record.acpxRecordId}\n`);
-	process.stdout.write(`sessionId: ${record.acpSessionId}\n`);
-	process.stdout.write(`agentSessionId: ${record.agentSessionId ?? "-"}\n`);
-	process.stdout.write(`agent: ${record.agentCommand}\n`);
-	process.stdout.write(`cwd: ${record.cwd}\n`);
-	process.stdout.write(`name: ${record.name ?? "-"}\n`);
-	process.stdout.write(`created: ${record.createdAt}\n`);
-	process.stdout.write(`lastActivity: ${record.lastUsedAt}\n`);
-	process.stdout.write(`lastPrompt: ${record.lastPromptAt ?? "-"}\n`);
-	process.stdout.write(`closed: ${record.closed ? "yes" : "no"}\n`);
-	process.stdout.write(`closedAt: ${record.closedAt ?? "-"}\n`);
-	process.stdout.write(`pid: ${record.pid ?? "-"}\n`);
-	process.stdout.write(`agentStartedAt: ${record.agentStartedAt ?? "-"}\n`);
-	process.stdout.write(`lastExitCode: ${record.lastAgentExitCode ?? "-"}\n`);
-	process.stdout.write(`lastExitSignal: ${record.lastAgentExitSignal ?? "-"}\n`);
-	process.stdout.write(`lastExitAt: ${record.lastAgentExitAt ?? "-"}\n`);
-	process.stdout.write(`disconnectReason: ${record.lastAgentDisconnectReason ?? "-"}\n`);
-	process.stdout.write(`historyEntries: ${conversationHistoryEntries(record).length}\n`);
+	for (const line of sessionDetailsLines(record)) process.stdout.write(`${line}\n`);
+}
+function sessionDetailsLines(record) {
+	return [
+		`id: ${record.acpxRecordId}`,
+		`sessionId: ${record.acpSessionId}`,
+		`agentSessionId: ${displayValue(record.agentSessionId)}`,
+		`agent: ${record.agentCommand}`,
+		`cwd: ${record.cwd}`,
+		`name: ${displayValue(record.name)}`,
+		`created: ${record.createdAt}`,
+		`lastActivity: ${record.lastUsedAt}`,
+		`lastPrompt: ${displayValue(record.lastPromptAt)}`,
+		`closed: ${record.closed ? "yes" : "no"}`,
+		`closedAt: ${displayValue(record.closedAt)}`,
+		`pid: ${displayValue(record.pid)}`,
+		`agentStartedAt: ${displayValue(record.agentStartedAt)}`,
+		`lastExitCode: ${displayValue(record.lastAgentExitCode)}`,
+		`lastExitSignal: ${displayValue(record.lastAgentExitSignal)}`,
+		`lastExitAt: ${displayValue(record.lastAgentExitAt)}`,
+		`disconnectReason: ${displayValue(record.lastAgentDisconnectReason)}`,
+		`historyEntries: ${conversationHistoryEntries(record).length}`
+	];
+}
+function displayValue(value) {
+	return value == null ? "-" : String(value);
 }
 function printSessionHistoryByFormat(record, limit, format) {
 	const history = conversationHistoryEntries(record);
@@ -565,6 +933,46 @@ async function handleSessionsHistory(explicitAgentName, sessionName, flags, comm
 	const globalFlags = resolveGlobalFlags(command, config);
 	printSessionHistoryByFormat(await findScopedSessionOrThrow(resolveAgentInvocation(explicitAgentName, globalFlags, config), sessionName), flags.limit, globalFlags.format);
 }
+async function handleSessionsExport(explicitAgentName, sessionName, flags, command, config) {
+	const globalFlags = resolveGlobalFlags(command, config);
+	const agent = resolveAgentInvocation(explicitAgentName, globalFlags, config);
+	const cwd = flags.sourceCwd ? path.resolve(agent.cwd, flags.sourceCwd) : agent.cwd;
+	await exportSession({
+		agentName: globalFlags.agent ? void 0 : agent.agentName,
+		agentCommand: agent.agentCommand,
+		cwd,
+		name: sessionName
+	}, flags.output);
+	if (emitJsonResult(globalFlags.format, {
+		action: "session_exported",
+		output: flags.output
+	})) return;
+	if (globalFlags.format === "quiet") {
+		process.stdout.write(`${flags.output}\n`);
+		return;
+	}
+	process.stdout.write(`exported session to ${flags.output}\n`);
+}
+async function handleSessionsImport(explicitAgentName, archivePath, flags, command, config) {
+	const globalFlags = resolveGlobalFlags(command, config);
+	const agent = resolveAgentInvocation(explicitAgentName, globalFlags, config);
+	const result = await importSession(archivePath, {
+		name: flags.name,
+		newCwd: flags.destinationCwd ? path.resolve(globalFlags.cwd, flags.destinationCwd) : void 0,
+		expectedAgentName: globalFlags.agent ? void 0 : agent.agentName,
+		expectedAgentCommand: agent.agentCommand
+	});
+	if (emitJsonResult(globalFlags.format, {
+		action: "session_imported",
+		record_id: result.record_id,
+		cwd: result.cwd
+	})) return;
+	if (globalFlags.format === "quiet") {
+		process.stdout.write(`${result.record_id}\n`);
+		return;
+	}
+	process.stdout.write(`imported session ${result.record_id} at ${result.cwd}\n`);
+}
 async function handleSessionsPrune(explicitAgentName, flags, command, config) {
 	const globalFlags = resolveGlobalFlags(command, config);
 	const agent = resolveAgentInvocation(explicitAgentName, globalFlags, config);
@@ -636,38 +1044,38 @@ function parseMeta(value, path) {
 	if (!asRecord$1(value)) throw new Error(`Invalid ${path}: expected object or null`);
 	return value;
 }
-function parseServer(rawServer, path) {
-	const serverRecord = asRecord$1(rawServer);
-	if (!serverRecord) throw new Error(`Invalid ${path}: expected object`);
-	const name = parseNonEmptyString(serverRecord.name, `${path}.name`);
-	const _meta = parseMeta(serverRecord._meta, `${path}._meta`);
-	const rawType = serverRecord.type;
-	let typeValue;
-	if (rawType === void 0) typeValue = "stdio";
-	else {
-		const parsedType = parseNonEmptyString(rawType, `${path}.type`);
-		if (parsedType !== "http" && parsedType !== "sse" && parsedType !== "stdio") throw new Error(`Invalid ${path}.type: expected http, sse, or stdio`);
-		typeValue = parsedType;
-	}
-	if (typeValue === "http" || typeValue === "sse") {
-		const url = parseNonEmptyString(serverRecord.url, `${path}.url`);
-		const headers = parseHeaders(serverRecord.headers, `${path}.headers`);
-		return {
-			type: typeValue,
-			name,
-			url,
-			headers,
-			_meta
-		};
-	}
-	if (typeValue === "stdio") return {
+function parseServerType(rawType, path) {
+	if (rawType === void 0) return "stdio";
+	const parsedType = parseNonEmptyString(rawType, `${path}.type`);
+	if (parsedType !== "http" && parsedType !== "sse" && parsedType !== "stdio") throw new Error(`Invalid ${path}.type: expected http, sse, or stdio`);
+	return parsedType;
+}
+function parseHttpServer(serverRecord, path, type, name, _meta) {
+	return {
+		type,
+		name,
+		url: parseNonEmptyString(serverRecord.url, `${path}.url`),
+		headers: parseHeaders(serverRecord.headers, `${path}.headers`),
+		_meta
+	};
+}
+function parseStdioServer(serverRecord, path, name, _meta) {
+	return {
 		name,
 		command: parseNonEmptyString(serverRecord.command, `${path}.command`),
 		args: parseArgs(serverRecord.args, `${path}.args`),
 		env: parseEnv(serverRecord.env, `${path}.env`),
 		_meta
 	};
-	throw new Error(`Invalid ${path}.type: expected http, sse, or stdio`);
+}
+function parseServer(rawServer, path) {
+	const serverRecord = asRecord$1(rawServer);
+	if (!serverRecord) throw new Error(`Invalid ${path}: expected object`);
+	const name = parseNonEmptyString(serverRecord.name, `${path}.name`);
+	const _meta = parseMeta(serverRecord._meta, `${path}._meta`);
+	const typeValue = parseServerType(serverRecord.type, path);
+	if (typeValue === "http" || typeValue === "sse") return parseHttpServer(serverRecord, path, typeValue, name, _meta);
+	return parseStdioServer(serverRecord, path, name, _meta);
 }
 function parseMcpServers(value, sourcePath, fieldName = "mcpServers") {
 	const fieldPath = `${fieldName} in ${sourcePath}`;
@@ -749,7 +1157,7 @@ function parseOutputFormat(value, sourcePath) {
 function parseDefaultAgent(value, sourcePath) {
 	if (value == null) return;
 	if (typeof value !== "string" || value.trim().length === 0) throw new Error(`Invalid config defaultAgent in ${sourcePath}: expected non-empty string`);
-	return normalizeAgentName(value);
+	return normalizeAgentName$1(value);
 }
 function parseAgents(value, sourcePath) {
 	if (value == null) return;
@@ -760,7 +1168,7 @@ function parseAgents(value, sourcePath) {
 		const command = raw.command;
 		if (typeof command !== "string" || command.trim().length === 0) throw new Error(`Invalid config agents.${name}.command in ${sourcePath}: expected non-empty string`);
 		const args = parseAgentArgs(raw.args, name, sourcePath);
-		parsed[normalizeAgentName(name)] = args.length > 0 ? `${command.trim()} ${args.map(quoteCommandArg).join(" ")}` : command.trim();
+		parsed[normalizeAgentName$1(name)] = args.length > 0 ? `${command.trim()} ${args.map(quoteCommandArg).join(" ")}` : command.trim();
 	}
 	return parsed;
 }
@@ -828,35 +1236,13 @@ async function loadResolvedConfig(cwd) {
 	const [globalResult, projectResult] = await Promise.all([readConfigFile(globalPath), readConfigFile(projectPath)]);
 	const globalConfig = globalResult.config;
 	const projectConfig = projectResult.config;
-	const defaultAgent = parseDefaultAgent(projectConfig?.defaultAgent, projectPath) ?? parseDefaultAgent(globalConfig?.defaultAgent, globalPath) ?? "codex";
-	const defaultPermissions = parsePermissionMode(projectConfig?.defaultPermissions, projectPath) ?? parsePermissionMode(globalConfig?.defaultPermissions, globalPath) ?? DEFAULT_PERMISSION_MODE;
-	const nonInteractivePermissions = parseNonInteractivePermissionPolicy(projectConfig?.nonInteractivePermissions, projectPath) ?? parseNonInteractivePermissionPolicy(globalConfig?.nonInteractivePermissions, globalPath) ?? DEFAULT_NON_INTERACTIVE_PERMISSION_POLICY;
-	const authPolicy = parseAuthPolicy(projectConfig?.authPolicy, projectPath) ?? parseAuthPolicy(globalConfig?.authPolicy, globalPath) ?? DEFAULT_AUTH_POLICY;
-	const ttlMs = parseTtlMs(projectConfig?.ttl, projectPath) ?? parseTtlMs(globalConfig?.ttl, globalPath) ?? DEFAULT_TTL_MS;
-	const timeoutConfiguredInProject = projectConfig != null && Object.prototype.hasOwnProperty.call(projectConfig, "timeout");
-	const timeoutConfiguredInGlobal = globalConfig != null && Object.prototype.hasOwnProperty.call(globalConfig, "timeout");
-	let timeoutMs = DEFAULT_TIMEOUT_MS;
-	if (timeoutConfiguredInProject) timeoutMs = parseTimeoutMs(projectConfig?.timeout, projectPath);
-	else if (timeoutConfiguredInGlobal) timeoutMs = parseTimeoutMs(globalConfig?.timeout, globalPath);
-	const format = parseOutputFormat(projectConfig?.format, projectPath) ?? parseOutputFormat(globalConfig?.format, globalPath) ?? DEFAULT_OUTPUT_FORMAT;
-	const queueMaxDepth = parseQueueMaxDepth(projectConfig?.queueMaxDepth, projectPath) ?? parseQueueMaxDepth(globalConfig?.queueMaxDepth, globalPath) ?? DEFAULT_QUEUE_MAX_DEPTH;
+	const scalar = resolveScalarConfigValues(projectConfig, projectPath, globalConfig, globalPath);
 	const agents = mergeAgents(parseAgents(globalConfig?.agents, globalPath), parseAgents(projectConfig?.agents, projectPath));
 	const auth = mergeAuth(parseAuth(globalConfig?.auth, globalPath), parseAuth(projectConfig?.auth, projectPath));
-	const mcpServersConfiguredInProject = projectConfig != null && Object.prototype.hasOwnProperty.call(projectConfig, "mcpServers");
-	const mcpServersConfiguredInGlobal = globalConfig != null && Object.prototype.hasOwnProperty.call(globalConfig, "mcpServers");
-	let mcpServers = [];
-	if (mcpServersConfiguredInProject) mcpServers = parseMcpServers(projectConfig?.mcpServers, projectPath);
-	else if (mcpServersConfiguredInGlobal) mcpServers = parseMcpServers(globalConfig?.mcpServers, globalPath);
-	const disableExec = parseDisableExec(projectConfig?.disableExec, projectPath) ?? parseDisableExec(globalConfig?.disableExec, globalPath) ?? DEFAULT_DISABLE_EXEC;
+	const mcpServers = resolveMcpServers(projectConfig, projectPath, globalConfig, globalPath);
+	const disableExec = resolveDisableExec(projectConfig, projectPath, globalConfig, globalPath);
 	return {
-		defaultAgent,
-		defaultPermissions,
-		nonInteractivePermissions,
-		authPolicy,
-		ttlMs,
-		timeoutMs,
-		queueMaxDepth,
-		format,
+		...scalar,
 		agents,
 		auth,
 		disableExec,
@@ -867,6 +1253,55 @@ async function loadResolvedConfig(cwd) {
 		hasProjectConfig: projectResult.exists
 	};
 }
+function resolveScalarConfigValues(projectConfig, projectPath, globalConfig, globalPath) {
+	return {
+		defaultAgent: resolveDefaultAgent(projectConfig, projectPath, globalConfig, globalPath),
+		defaultPermissions: resolveDefaultPermissions(projectConfig, projectPath, globalConfig, globalPath),
+		nonInteractivePermissions: resolveNonInteractivePermissions(projectConfig, projectPath, globalConfig, globalPath),
+		authPolicy: resolveAuthPolicy(projectConfig, projectPath, globalConfig, globalPath),
+		ttlMs: resolveTtlMs(projectConfig, projectPath, globalConfig, globalPath),
+		timeoutMs: resolveTimeoutMs(projectConfig, projectPath, globalConfig, globalPath),
+		queueMaxDepth: resolveQueueMaxDepth(projectConfig, projectPath, globalConfig, globalPath),
+		format: resolveFormat(projectConfig, projectPath, globalConfig, globalPath)
+	};
+}
+function resolveDefaultAgent(projectConfig, projectPath, globalConfig, globalPath) {
+	return parseDefaultAgent(projectConfig?.defaultAgent, projectPath) ?? parseDefaultAgent(globalConfig?.defaultAgent, globalPath) ?? "codex";
+}
+function resolveDefaultPermissions(projectConfig, projectPath, globalConfig, globalPath) {
+	return parsePermissionMode(projectConfig?.defaultPermissions, projectPath) ?? parsePermissionMode(globalConfig?.defaultPermissions, globalPath) ?? DEFAULT_PERMISSION_MODE;
+}
+function resolveNonInteractivePermissions(projectConfig, projectPath, globalConfig, globalPath) {
+	return parseNonInteractivePermissionPolicy(projectConfig?.nonInteractivePermissions, projectPath) ?? parseNonInteractivePermissionPolicy(globalConfig?.nonInteractivePermissions, globalPath) ?? DEFAULT_NON_INTERACTIVE_PERMISSION_POLICY;
+}
+function resolveAuthPolicy(projectConfig, projectPath, globalConfig, globalPath) {
+	return parseAuthPolicy(projectConfig?.authPolicy, projectPath) ?? parseAuthPolicy(globalConfig?.authPolicy, globalPath) ?? DEFAULT_AUTH_POLICY;
+}
+function resolveTtlMs(projectConfig, projectPath, globalConfig, globalPath) {
+	return parseTtlMs(projectConfig?.ttl, projectPath) ?? parseTtlMs(globalConfig?.ttl, globalPath) ?? DEFAULT_TTL_MS;
+}
+function resolveQueueMaxDepth(projectConfig, projectPath, globalConfig, globalPath) {
+	return parseQueueMaxDepth(projectConfig?.queueMaxDepth, projectPath) ?? parseQueueMaxDepth(globalConfig?.queueMaxDepth, globalPath) ?? DEFAULT_QUEUE_MAX_DEPTH;
+}
+function resolveFormat(projectConfig, projectPath, globalConfig, globalPath) {
+	return parseOutputFormat(projectConfig?.format, projectPath) ?? parseOutputFormat(globalConfig?.format, globalPath) ?? DEFAULT_OUTPUT_FORMAT;
+}
+function hasConfigKey(config, key) {
+	return config != null && Object.prototype.hasOwnProperty.call(config, key);
+}
+function resolveTimeoutMs(projectConfig, projectPath, globalConfig, globalPath) {
+	if (hasConfigKey(projectConfig, "timeout")) return parseTimeoutMs(projectConfig?.timeout, projectPath);
+	if (hasConfigKey(globalConfig, "timeout")) return parseTimeoutMs(globalConfig?.timeout, globalPath);
+	return DEFAULT_TIMEOUT_MS;
+}
+function resolveMcpServers(projectConfig, projectPath, globalConfig, globalPath) {
+	if (hasConfigKey(projectConfig, "mcpServers")) return parseMcpServers(projectConfig?.mcpServers, projectPath);
+	if (hasConfigKey(globalConfig, "mcpServers")) return parseMcpServers(globalConfig?.mcpServers, globalPath);
+	return [];
+}
+function resolveDisableExec(projectConfig, projectPath, globalConfig, globalPath) {
+	return parseDisableExec(projectConfig?.disableExec, projectPath) ?? parseDisableExec(globalConfig?.disableExec, globalPath) ?? DEFAULT_DISABLE_EXEC;
+}
 function toConfigDisplay(config) {
 	const agents = {};
 	for (const [name, command] of Object.entries(config.agents)) agents[name] = { command };
@@ -970,6 +1405,7 @@ function registerConfigCommand(program, config) {
 var render_exports = /* @__PURE__ */ __exportAll({
 	agentSessionIdPayload: () => agentSessionIdPayload,
 	formatPromptSessionBannerLine: () => formatPromptSessionBannerLine,
+	printAgentSessionsByFormat: () => printAgentSessionsByFormat,
 	printClosedSessionByFormat: () => printClosedSessionByFormat,
 	printCreatedSessionBanner: () => printCreatedSessionBanner,
 	printEnsuredSessionByFormat: () => printEnsuredSessionByFormat,
@@ -996,10 +1432,7 @@ function printSessionsByFormat(sessions, format) {
 		return;
 	}
 	if (format === "quiet") {
-		for (const session of sessions) {
-			const closedMarker = session.closed ? " [closed]" : "";
-			process.stdout.write(`${session.acpxRecordId}${closedMarker}\n`);
-		}
+		printQuietSessions(sessions);
 		return;
 	}
 	if (sessions.length === 0) {
@@ -1011,6 +1444,36 @@ function printSessionsByFormat(sessions, format) {
 		process.stdout.write(`${session.acpxRecordId}${closedMarker}\t${session.name ?? "-"}\t${session.cwd}\t${session.lastUsedAt}\n`);
 	}
 }
+function printQuietSessions(sessions) {
+	for (const session of sessions) {
+		const closedMarker = session.closed ? " [closed]" : "";
+		process.stdout.write(`${session.acpxRecordId}${closedMarker}\n`);
+	}
+}
+function printAgentSessionsByFormat(result, format) {
+	if (format === "json") {
+		process.stdout.write(`${JSON.stringify(result)}\n`);
+		return;
+	}
+	if (format === "quiet") {
+		printQuietAgentSessions(result);
+		return;
+	}
+	printTextAgentSessions(result);
+}
+function printQuietAgentSessions(result) {
+	for (const session of result.sessions) process.stdout.write(`${session.sessionId}\n`);
+}
+function printTextAgentSessions(result) {
+	if (result.sessions.length === 0) process.stdout.write("No sessions\n");
+	else for (const session of result.sessions) {
+		const title = session.title ?? "-";
+		const updatedAt = session.updatedAt ?? "-";
+		const meta = session._meta ? JSON.stringify(session._meta) : "-";
+		process.stdout.write(`${session.sessionId}\t${title}\t${session.cwd}\t${updatedAt}\t${meta}\n`);
+	}
+	if (result.nextCursor) process.stdout.write(`Next cursor: ${result.nextCursor}\n`);
+}
 function printClosedSessionByFormat(record, format) {
 	if (emitJsonResult(format, {
 		action: "session_closed",
@@ -1095,29 +1558,38 @@ function formatBytes(bytes) {
 }
 function printPruneResultByFormat(result, format) {
 	const count = result.pruned.length;
-	if (emitJsonResult(format, {
-		action: result.dryRun ? "sessions_prune_dry_run" : "sessions_pruned",
-		dryRun: result.dryRun,
-		count,
-		bytesFreed: result.bytesFreed,
-		pruned: result.pruned.map((r) => r.acpxRecordId)
-	})) return;
+	if (emitPruneJsonResult(result, format, count)) return;
 	if (format === "quiet") {
-		for (const record of result.pruned) process.stdout.write(`${record.acpxRecordId}\n`);
+		printQuietPruneResult(result.pruned);
 		return;
 	}
 	if (count === 0) {
 		process.stdout.write(result.dryRun ? "[DRY RUN] No sessions to prune\n" : "No sessions pruned\n");
 		return;
 	}
-	const prefix = result.dryRun ? "[DRY RUN] Would prune" : "Pruned";
-	const bytesSuffix = !result.dryRun && result.bytesFreed > 0 ? `, freed ${formatBytes(result.bytesFreed)}` : "";
-	process.stdout.write(`${prefix} ${count} session${count === 1 ? "" : "s"}${bytesSuffix}\n`);
+	process.stdout.write(`${formatPruneSummaryLine(result, count)}\n`);
 	for (const record of result.pruned) {
 		const label = record.name ? ` (${record.name})` : "";
 		process.stdout.write(`  ${record.acpxRecordId}${label}\t${record.closedAt ?? record.lastUsedAt}\n`);
 	}
 }
+function emitPruneJsonResult(result, format, count) {
+	return emitJsonResult(format, {
+		action: result.dryRun ? "sessions_prune_dry_run" : "sessions_pruned",
+		dryRun: result.dryRun,
+		count,
+		bytesFreed: result.bytesFreed,
+		pruned: result.pruned.map((r) => r.acpxRecordId)
+	});
+}
+function printQuietPruneResult(pruned) {
+	for (const record of pruned) process.stdout.write(`${record.acpxRecordId}\n`);
+}
+function formatPruneSummaryLine(result, count) {
+	const prefix = result.dryRun ? "[DRY RUN] Would prune" : "Pruned";
+	const bytesSuffix = !result.dryRun && result.bytesFreed > 0 ? `, freed ${formatBytes(result.bytesFreed)}` : "";
+	return `${prefix} ${count} session${count === 1 ? "" : "s"}${bytesSuffix}`;
+}
 function agentSessionIdPayload(agentSessionId) {
 	const normalized = normalizeRuntimeSessionId(agentSessionId);
 	if (!normalized) return {};
@@ -1159,63 +1631,115 @@ async function handleStatus(explicitAgentName, flags, command, config) {
 		name: resolveSessionNameFromFlags(flags, command)
 	});
 	if (!record) {
-		if (emitJsonResult(globalFlags.format, {
-			action: "status_snapshot",
-			status: "no-session",
-			summary: "no active session"
-		})) return;
-		if (globalFlags.format === "quiet") {
-			process.stdout.write("no-session\n");
-			return;
-		}
-		process.stdout.write("session: -\n");
-		process.stdout.write(`agent: ${agent.agentCommand}\n`);
-		process.stdout.write("pid: -\n");
-		process.stdout.write("status: no-session\n");
-		process.stdout.write("model: -\n");
-		process.stdout.write("mode: -\n");
-		process.stdout.write("uptime: -\n");
-		process.stdout.write("lastPromptTime: -\n");
+		printMissingStatus(globalFlags.format, agent.agentCommand);
+		return;
+	}
+	await printSessionStatus(record, globalFlags.format);
+}
+function printMissingStatus(format, agentCommand) {
+	if (emitJsonResult(format, {
+		action: "status_snapshot",
+		status: "no-session",
+		summary: "no active session"
+	})) return;
+	if (format === "quiet") {
+		process.stdout.write("no-session\n");
 		return;
 	}
+	process.stdout.write("session: -\n");
+	process.stdout.write(`agent: ${agentCommand}\n`);
+	process.stdout.write("pid: -\n");
+	process.stdout.write("status: no-session\n");
+	process.stdout.write("model: -\n");
+	process.stdout.write("mode: -\n");
+	process.stdout.write("uptime: -\n");
+	process.stdout.write("lastPromptTime: -\n");
+}
+async function printSessionStatus(record, format) {
 	const health = await probeQueueOwnerHealth(record.acpxRecordId);
 	const statusState = resolveStatusState(record, health);
-	const running = statusState === "running";
-	const dead = statusState === "dead";
-	const payload = {
+	const payload = createStatusPayload(record, health, statusState);
+	const running = isRunningStatus(statusState);
+	const dead = isDeadStatus(statusState);
+	if (emitStatusJson(format, record, payload, statusState, running, dead)) return;
+	if (format === "quiet") {
+		process.stdout.write(`${payload.status}\n`);
+		return;
+	}
+	printTextStatus(payload, dead);
+}
+function createStatusPayload(record, health, statusState) {
+	const running = isRunningStatus(statusState);
+	const acpx = statusAcpxFields(record);
+	return {
 		sessionId: record.acpxRecordId,
 		agentCommand: record.agentCommand,
-		pid: health.pid ?? record.pid ?? null,
+		pid: statusPid(health),
 		status: statusState,
+		model: acpx.model,
+		mode: acpx.mode,
+		availableModels: acpx.availableModels,
+		uptime: running ? optionalStatusString(formatUptime(record.agentStartedAt)) : null,
+		lastPromptTime: optionalStatusString(record.lastPromptAt),
+		exitCode: running ? null : optionalStatusNumber(record.lastAgentExitCode),
+		signal: running ? null : optionalStatusSignal(record.lastAgentExitSignal),
+		...agentSessionIdPayload(record.agentSessionId)
+	};
+}
+function statusAcpxFields(record) {
+	return {
 		model: record.acpx?.current_model_id ?? null,
 		mode: record.acpx?.current_mode_id ?? null,
-		availableModels: record.acpx?.available_models ?? null,
-		uptime: running ? formatUptime(record.agentStartedAt) ?? null : null,
-		lastPromptTime: record.lastPromptAt ?? null,
-		exitCode: running ? null : record.lastAgentExitCode ?? null,
-		signal: running ? null : record.lastAgentExitSignal ?? null,
-		...agentSessionIdPayload(record.agentSessionId)
+		availableModels: record.acpx?.available_models ?? null
 	};
-	if (emitJsonResult(globalFlags.format, {
+}
+function statusPid(health) {
+	if (health.pidAlive) return health.pid ?? null;
+	return null;
+}
+function optionalStatusString(value) {
+	return value ?? null;
+}
+function optionalStatusNumber(value) {
+	return value ?? null;
+}
+function optionalStatusSignal(value) {
+	return value ?? null;
+}
+function isRunningStatus(status) {
+	return status === "running";
+}
+function isDeadStatus(status) {
+	return status === "dead";
+}
+function emitStatusJson(format, record, payload, statusState, running, dead) {
+	return emitJsonResult(format, statusJsonPayload(record, payload, statusState, running, dead));
+}
+function statusJsonPayload(record, payload, statusState, running, dead) {
+	const result = {
 		action: "status_snapshot",
 		status: running ? "alive" : statusState,
-		pid: payload.pid ?? void 0,
 		summary: statusSummary(statusState),
-		model: payload.model ?? void 0,
-		mode: payload.mode ?? void 0,
-		availableModels: payload.availableModels ?? void 0,
-		uptime: payload.uptime ?? void 0,
-		lastPromptTime: payload.lastPromptTime ?? void 0,
-		exitCode: dead ? payload.exitCode ?? void 0 : void 0,
-		signal: dead ? payload.signal ?? void 0 : void 0,
 		acpxRecordId: record.acpxRecordId,
 		acpxSessionId: record.acpSessionId,
 		agentSessionId: record.agentSessionId
-	})) return;
-	if (globalFlags.format === "quiet") {
-		process.stdout.write(`${payload.status}\n`);
-		return;
+	};
+	assignDefinedJsonField(result, "pid", payload.pid);
+	assignDefinedJsonField(result, "model", payload.model);
+	assignDefinedJsonField(result, "mode", payload.mode);
+	assignDefinedJsonField(result, "availableModels", payload.availableModels);
+	assignDefinedJsonField(result, "uptime", payload.uptime);
+	assignDefinedJsonField(result, "lastPromptTime", payload.lastPromptTime);
+	if (dead) {
+		assignDefinedJsonField(result, "exitCode", payload.exitCode);
+		assignDefinedJsonField(result, "signal", payload.signal);
 	}
+	return result;
+}
+function assignDefinedJsonField(target, key, value) {
+	if (value !== null && value !== void 0) target[key] = value;
+}
+function printTextStatus(payload, dead) {
 	process.stdout.write(`session: ${payload.sessionId}\n`);
 	if ("agentSessionId" in payload) process.stdout.write(`agentSessionId: ${payload.agentSessionId}\n`);
 	process.stdout.write(`agent: ${payload.agentCommand}\n`);
@@ -1225,10 +1749,11 @@ async function handleStatus(explicitAgentName, flags, command, config) {
 	process.stdout.write(`mode: ${payload.mode ?? "-"}\n`);
 	process.stdout.write(`uptime: ${payload.uptime ?? "-"}\n`);
 	process.stdout.write(`lastPromptTime: ${payload.lastPromptTime ?? "-"}\n`);
-	if (dead) {
-		process.stdout.write(`exitCode: ${payload.exitCode ?? "-"}\n`);
-		process.stdout.write(`signal: ${payload.signal ?? "-"}\n`);
-	}
+	if (dead) printDeadStatusDetails(payload);
+}
+function printDeadStatusDetails(payload) {
+	process.stdout.write(`exitCode: ${payload.exitCode ?? "-"}\n`);
+	process.stdout.write(`signal: ${payload.signal ?? "-"}\n`);
 }
 function registerStatusCommand(parent, explicitAgentName, config, description) {
 	const statusCommand = parent.command("status").description(description);
@@ -1239,13 +1764,27 @@ function registerStatusCommand(parent, explicitAgentName, config, description) {
 }
 //#endregion
 //#region src/cli/command-registration.ts
+var LocalAttributeOption = class extends Option {
+	localAttributeName;
+	constructor(flags, description, localAttributeName) {
+		super(flags, description);
+		this.localAttributeName = localAttributeName;
+	}
+	attributeName() {
+		return this.localAttributeName;
+	}
+};
+function addSessionsListOptions(command) {
+	return command.option("--local", "List local acpx session records instead of agent protocol sessions").option("--cursor <cursor>", "Opaque ACP session/list cursor", (value) => parseNonEmptyValue("Cursor", value)).option("--filter-cwd <dir>", "Filter agent sessions by working directory", (value) => parseNonEmptyValue("Filter cwd", value));
+}
 function registerSessionsCommand(parent, explicitAgentName, config) {
 	const sessionsCommand = parent.command("sessions").description("List, ensure, create, or close sessions for this agent");
-	sessionsCommand.action(async function() {
-		await handleSessionsList(explicitAgentName, this, config);
+	addSessionsListOptions(sessionsCommand);
+	sessionsCommand.action(async function(flags) {
+		await handleSessionsList(explicitAgentName, flags, this, config);
 	});
-	sessionsCommand.command("list").description("List sessions").action(async function() {
-		await handleSessionsList(explicitAgentName, this, config);
+	addSessionsListOptions(sessionsCommand.command("list")).description("List sessions").action(async function(flags) {
+		await handleSessionsList(explicitAgentName, flags, this, config);
 	});
 	sessionsCommand.command("new").description("Create a fresh session for current cwd").option("-s, --name <name>", "Session name", parseSessionName).option("--resume-session <id>", "Resume existing ACP session id", (value) => parseNonEmptyValue("Resume session id", value)).action(async function(flags) {
 		await handleSessionsNew(explicitAgentName, flags, this, config);
@@ -1265,6 +1804,12 @@ function registerSessionsCommand(parent, explicitAgentName, config) {
 	sessionsCommand.command("read").description("Read full session history").argument("[name]", "Session name", parseSessionName).option("--tail <count>", "Show only the last N entries instead of all history", parseHistoryLimit).action(async function(name, flags) {
 		await handleSessionsHistory(explicitAgentName, name, { limit: flags.tail ?? 0 }, this, config);
 	});
+	sessionsCommand.command("export").description("Export a portable session archive").argument("[name]", "Session name", parseSessionName).requiredOption("--output <path>", "Output archive path", (value) => parseNonEmptyValue("Output path", value)).addOption(new LocalAttributeOption("--cwd <cwd>", "Session cwd to export", "sourceCwd").argParser((value) => parseNonEmptyValue("Session cwd", value))).action(async function(name, flags) {
+		await handleSessionsExport(explicitAgentName, name, flags, this, config);
+	});
+	sessionsCommand.command("import").description("Import a portable session archive").argument("<archive-path>", "Archive path", (value) => parseNonEmptyValue("Archive path", value)).option("--name <name>", "Imported session name", parseSessionName).addOption(new LocalAttributeOption("--cwd <cwd>", "Imported session cwd", "destinationCwd").argParser((value) => parseNonEmptyValue("Imported session cwd", value))).action(async function(archivePath, flags) {
+		await handleSessionsImport(explicitAgentName, archivePath, flags, this, config);
+	});
 	sessionsCommand.command("prune").description("Delete closed sessions and free disk space").option("--dry-run", "Preview what would be pruned without deleting anything").option("--before <date>", "Prune sessions closed before this date", parsePruneBeforeDate).option("--older-than <days>", "Prune sessions closed more than N days ago", parseDaysOlderThan).option("--include-history", "Also delete event stream files (.stream.ndjson)").action(async function(flags) {
 		await handleSessionsPrune(explicitAgentName, flags, this, config);
 	});
@@ -1317,7 +1862,7 @@ function registerAgentCommand(program, agentName, config) {
 }
 function registerFlowCommand(program, config) {
 	program.command("flow").description("Run multi-step ACP workflows from flow files").command("run").description("Run a flow file").argument("<file>", "Flow module path").option("--input-json <json>", "Flow input as JSON").option("--input-file <path>", "Read flow input JSON from file").option("--default-agent <name>", "Default agent profile for ACP nodes without profile", (value) => parseNonEmptyValue("Default agent", value)).action(async function(file, flags) {
-		const { handleFlowRun } = await import("./cli-BGYGVo3b.js");
+		const { handleFlowRun } = await import("./cli-8dP_TqBp.js");
 		await handleFlowRun(file, flags, this, config);
 	});
 }
@@ -1349,33 +1894,63 @@ function parseQueueOwnerPayload(raw) {
 		sessionId: record.sessionId,
 		permissionMode: record.permissionMode
 	};
+	assignQueueOwnerTransportOptions(options, record);
+	assignQueueOwnerScalarOptions(options, record);
+	assignQueueOwnerSessionOptions(options, record.sessionOptions);
+	return options;
+}
+function assignQueueOwnerTransportOptions(options, record) {
 	const parsedMcpServers = parseOptionalMcpServers(record.mcpServers, "queue owner payload");
 	if (parsedMcpServers) options.mcpServers = parsedMcpServers;
-	if (typeof record.nonInteractivePermissions === "string") options.nonInteractivePermissions = record.nonInteractivePermissions === "deny" || record.nonInteractivePermissions === "fail" ? record.nonInteractivePermissions : void 0;
 	if (record.authCredentials && typeof record.authCredentials === "object") {
 		const entries = Object.entries(record.authCredentials).filter(([, value]) => typeof value === "string");
 		options.authCredentials = Object.fromEntries(entries);
 	}
+}
+function assignQueueOwnerScalarOptions(options, record) {
+	if (record.nonInteractivePermissions === "deny" || record.nonInteractivePermissions === "fail") options.nonInteractivePermissions = record.nonInteractivePermissions;
 	if (record.authPolicy === "skip" || record.authPolicy === "fail") options.authPolicy = record.authPolicy;
-	if (typeof record.terminal === "boolean") options.terminal = record.terminal;
-	if (typeof record.suppressSdkConsoleErrors === "boolean") options.suppressSdkConsoleErrors = record.suppressSdkConsoleErrors;
-	if (typeof record.verbose === "boolean") options.verbose = record.verbose;
-	if (typeof record.ttlMs === "number" && Number.isFinite(record.ttlMs)) options.ttlMs = record.ttlMs;
-	if (typeof record.maxQueueDepth === "number" && Number.isFinite(record.maxQueueDepth)) options.maxQueueDepth = Math.max(1, Math.round(record.maxQueueDepth));
-	if (typeof record.promptRetries === "number" && Number.isFinite(record.promptRetries)) options.promptRetries = Math.max(0, Math.round(record.promptRetries));
-	const sessionOpts = asRecord(record.sessionOptions);
-	if (sessionOpts) {
-		options.sessionOptions = {};
-		if (typeof sessionOpts.model === "string" && sessionOpts.model.trim().length > 0) options.sessionOptions.model = sessionOpts.model;
-		if (Array.isArray(sessionOpts.allowedTools)) options.sessionOptions.allowedTools = sessionOpts.allowedTools.filter((tool) => typeof tool === "string");
-		if (typeof sessionOpts.maxTurns === "number" && Number.isFinite(sessionOpts.maxTurns)) options.sessionOptions.maxTurns = Math.max(1, Math.round(sessionOpts.maxTurns));
-		if (typeof sessionOpts.systemPrompt === "string") options.sessionOptions.systemPrompt = sessionOpts.systemPrompt;
-		else {
-			const systemPrompt = asRecord(sessionOpts.systemPrompt);
-			if (typeof systemPrompt?.append === "string") options.sessionOptions.systemPrompt = { append: systemPrompt.append };
-		}
+	assignBooleanOption(options, "terminal", record.terminal);
+	assignBooleanOption(options, "suppressSdkConsoleErrors", record.suppressSdkConsoleErrors);
+	assignBooleanOption(options, "verbose", record.verbose);
+	assignFiniteNumberOption(options, "ttlMs", record.ttlMs);
+	assignRoundedNumberOption(options, "maxQueueDepth", record.maxQueueDepth, 1);
+	assignRoundedNumberOption(options, "promptRetries", record.promptRetries, 0);
+}
+function assignBooleanOption(options, key, value) {
+	if (typeof value === "boolean") options[key] = value;
+}
+function assignFiniteNumberOption(options, key, value) {
+	if (typeof value === "number" && Number.isFinite(value)) options[key] = value;
+}
+function assignRoundedNumberOption(options, key, value, min) {
+	if (typeof value === "number" && Number.isFinite(value)) options[key] = Math.max(min, Math.round(value));
+}
+function assignQueueOwnerSessionOptions(options, rawSessionOptions) {
+	const sessionOpts = asRecord(rawSessionOptions);
+	if (!sessionOpts) return;
+	options.sessionOptions = {};
+	assignSessionModel(options.sessionOptions, sessionOpts.model);
+	assignSessionAllowedTools(options.sessionOptions, sessionOpts.allowedTools);
+	assignSessionMaxTurns(options.sessionOptions, sessionOpts.maxTurns);
+	assignSessionSystemPrompt(options.sessionOptions, sessionOpts.systemPrompt);
+}
+function assignSessionModel(options, value) {
+	if (typeof value === "string" && value.trim().length > 0) options.model = value;
+}
+function assignSessionAllowedTools(options, value) {
+	if (Array.isArray(value)) options.allowedTools = value.filter((tool) => typeof tool === "string");
+}
+function assignSessionMaxTurns(options, value) {
+	if (typeof value === "number" && Number.isFinite(value)) options.maxTurns = Math.max(1, Math.round(value));
+}
+function assignSessionSystemPrompt(options, value) {
+	if (typeof value === "string") {
+		options.systemPrompt = value;
+		return;
 	}
-	return options;
+	const systemPrompt = asRecord(value);
+	if (typeof systemPrompt?.append === "string") options.systemPrompt = { append: systemPrompt.append };
 }
 async function runQueueOwnerFromEnv(env) {
 	const payload = env.ACPX_QUEUE_OWNER_PAYLOAD;
@@ -1410,13 +1985,16 @@ function resolveVersionFromAncestors(startDir) {
 	}
 }
 function resolveAcpxVersion(params) {
-	const env = params?.env ?? process.env;
-	const envPackageName = parseVersion(env.npm_package_name);
-	const envVersion = parseVersion(env.npm_package_version);
-	if (envPackageName === "acpx" && envVersion) return envVersion;
+	const envVersion = resolvePackageEnvVersion(params?.env ?? process.env);
+	if (envVersion) return envVersion;
 	if (params?.packageJsonPath) return readPackageVersion(params.packageJsonPath) ?? UNKNOWN_VERSION;
 	return resolveVersionFromAncestors(MODULE_DIR) ?? UNKNOWN_VERSION;
 }
+function resolvePackageEnvVersion(env) {
+	const envPackageName = parseVersion(env.npm_package_name);
+	const envVersion = parseVersion(env.npm_package_version);
+	return envPackageName === "acpx" ? envVersion : null;
+}
 function getAcpxVersion() {
 	if (cachedVersion) return cachedVersion;
 	cachedVersion = resolveAcpxVersion();
@@ -1436,6 +2014,36 @@ const TOP_LEVEL_VERBS = new Set([
 	"config",
 	"help"
 ]);
+const TOP_LEVEL_VERSION_VALUE_FLAG_VALUES = [
+	"--agent",
+	"--cwd",
+	"--auth-policy",
+	"--non-interactive-permissions",
+	"--permission-policy",
+	"--policy",
+	"--format",
+	"--model",
+	"--allowed-tools",
+	"--max-turns",
+	"--system-prompt",
+	"--append-system-prompt",
+	"--prompt-retries",
+	"--timeout",
+	"--ttl"
+];
+const TOP_LEVEL_VERSION_VALUE_FLAGS = new Set(TOP_LEVEL_VERSION_VALUE_FLAG_VALUES);
+const TOP_LEVEL_VERSION_BOOLEAN_FLAGS = new Set([
+	"--approve-all",
+	"--approve-reads",
+	"--deny-all",
+	"--suppress-reads",
+	"--json-strict",
+	"--no-terminal",
+	"--verbose"
+]);
+const AGENT_SCAN_VALUE_FLAG_VALUES = [...TOP_LEVEL_VERSION_VALUE_FLAG_VALUES, "--file"];
+const AGENT_SCAN_VALUE_FLAGS = new Set(AGENT_SCAN_VALUE_FLAG_VALUES);
+const AGENT_SCAN_BOOLEAN_FLAGS = new Set(TOP_LEVEL_VERSION_BOOLEAN_FLAGS);
 let skillflagModulePromise;
 function loadSkillflagModule() {
 	skillflagModulePromise ??= import("skillflag");
@@ -1444,31 +2052,48 @@ function loadSkillflagModule() {
 function shouldMaybeHandleSkillflag(argv) {
 	return argv.some((token) => token === "--skill" || token.startsWith("--skill="));
 }
+function matchesLongFlagValue(token, flags) {
+	for (const flag of flags) if (token.startsWith(`${flag}=`)) return true;
+	return false;
+}
+function classifyAgentTokenFlag(token) {
+	if (token === "--agent" || token.startsWith("--agent=")) return "agent-value";
+	if (AGENT_SCAN_VALUE_FLAGS.has(token)) return "skip-next";
+	if (AGENT_SCAN_BOOLEAN_FLAGS.has(token) || matchesLongFlagValue(token, AGENT_SCAN_VALUE_FLAGS) || token.startsWith("--json-strict=")) return "skip";
+	return "unknown";
+}
+function scanAgentTokenStep(token, hasAgentOverride) {
+	if (token === "--") return {
+		result: { hasAgentOverride },
+		indexDelta: 0
+	};
+	if (!token.startsWith("-") || token === "-") return {
+		result: {
+			token,
+			hasAgentOverride
+		},
+		indexDelta: 0
+	};
+	const flagScan = classifyAgentTokenFlag(token);
+	if (flagScan === "agent-value") return {
+		indexDelta: token === "--agent" ? 1 : 0,
+		hasAgentOverride: true
+	};
+	if (flagScan === "skip-next") return { indexDelta: 1 };
+	if (flagScan === "skip") return { indexDelta: 0 };
+	return {
+		result: { hasAgentOverride },
+		indexDelta: 0
+	};
+}
 function detectAgentToken(argv) {
 	let hasAgentOverride = false;
 	for (let index = 0; index < argv.length; index += 1) {
 		const token = argv[index];
-		if (token === "--") break;
-		if (!token.startsWith("-") || token === "-") return {
-			token,
-			hasAgentOverride
-		};
-		if (token === "--agent") {
-			hasAgentOverride = true;
-			index += 1;
-			continue;
-		}
-		if (token.startsWith("--agent=")) {
-			hasAgentOverride = true;
-			continue;
-		}
-		if (token === "--cwd" || token === "--auth-policy" || token === "--non-interactive-permissions" || token === "--permission-policy" || token === "--policy" || token === "--format" || token === "--model" || token === "--allowed-tools" || token === "--max-turns" || token === "--timeout" || token === "--ttl" || token === "--file") {
-			index += 1;
-			continue;
-		}
-		if (token.startsWith("--cwd=") || token.startsWith("--auth-policy=") || token.startsWith("--non-interactive-permissions=") || token.startsWith("--permission-policy=") || token.startsWith("--policy=") || token.startsWith("--format=") || token.startsWith("--model=") || token.startsWith("--allowed-tools=") || token.startsWith("--max-turns=") || token.startsWith("--json-strict=") || token.startsWith("--timeout=") || token.startsWith("--ttl=") || token.startsWith("--file=")) continue;
-		if (token === "--approve-all" || token === "--approve-reads" || token === "--deny-all" || token === "--json-strict" || token === "--verbose" || token === "--suppress-reads") continue;
-		return { hasAgentOverride };
+		const step = scanAgentTokenStep(token, hasAgentOverride);
+		if (step.result) return step.result;
+		if (step.hasAgentOverride) hasAgentOverride = true;
+		index += step.indexDelta;
 	}
 	return { hasAgentOverride };
 }
@@ -1494,24 +2119,52 @@ function detectRequestedOutputFormat(argv, fallback) {
 	for (let index = 0; index < argv.length; index += 1) {
 		const token = argv[index];
 		if (token === "--") break;
-		if (token === "--json-strict" || token.startsWith("--json-strict=")) return "json";
-		if (token === "--format") {
-			const raw = argv[index + 1];
-			if (raw && OUTPUT_FORMATS.includes(raw)) detectedFormat = raw;
-			continue;
-		}
-		if (token.startsWith("--format=")) {
-			const raw = token.slice(9).trim();
-			if (OUTPUT_FORMATS.includes(raw)) detectedFormat = raw;
-		}
+		if (isJsonStrictToken(token)) return "json";
+		const format = readFormatFlagValue(token, argv[index + 1]);
+		if (format) detectedFormat = format;
 	}
 	return detectedFormat;
 }
+function readFormatFlagValue(token, nextToken) {
+	const raw = token === "--format" ? nextToken : readInlineFlagValue(token, "--format");
+	return isOutputFormat(raw) ? raw : void 0;
+}
+function readInlineFlagValue(token, flag) {
+	if (!token.startsWith(`${flag}=`)) return;
+	return token.slice(flag.length + 1).trim();
+}
+function isOutputFormat(value) {
+	return typeof value === "string" && OUTPUT_FORMATS.includes(value);
+}
+function isJsonStrictToken(token) {
+	return token === "--json-strict" || token.startsWith("--json-strict=");
+}
 function detectJsonStrict(argv) {
 	for (let index = 0; index < argv.length; index += 1) {
 		const token = argv[index];
 		if (token === "--") break;
-		if (token === "--json-strict" || token.startsWith("--json-strict=")) return true;
+		if (isJsonStrictToken(token)) return true;
+	}
+	return false;
+}
+function shouldSkipTopLevelVersionToken(token) {
+	return matchesLongFlagValue(token, TOP_LEVEL_VERSION_VALUE_FLAG_VALUES) || TOP_LEVEL_VERSION_BOOLEAN_FLAGS.has(token);
+}
+function topLevelVersionTokenDecision(token) {
+	if (token === "--version" || token === "-V") return "version";
+	if (!token.startsWith("-") || token === "-") return "stop";
+	if (TOP_LEVEL_VERSION_VALUE_FLAGS.has(token)) return "skip-next";
+	if (shouldSkipTopLevelVersionToken(token)) return "skip";
+	return "stop";
+}
+function isTopLevelVersionRequest(argv) {
+	for (let index = 0; index < argv.length; index += 1) {
+		const token = argv[index];
+		if (token === "--") return false;
+		const decision = topLevelVersionTokenDecision(token);
+		if (decision === "version") return true;
+		if (decision === "stop") return false;
+		if (decision === "skip-next") index += 1;
 	}
 	return false;
 }
@@ -1541,43 +2194,74 @@ async function emitRequestedError(error, normalized, outputPolicy) {
 async function runWithOutputPolicy(_outputPolicy, run) {
 	return await run();
 }
-async function main(argv = process.argv) {
+async function handleQueueOwnerCommand(argv) {
 	installPerfMetricsCapture({
 		argv: argv.slice(2),
 		role: argv[2] === "__queue-owner" ? "queue_owner" : "cli"
 	});
-	if (argv.includes("--version") || argv.includes("-V")) {
-		process.stdout.write(`${getAcpxVersion()}\n`);
-		return;
-	}
-	if (argv[2] === "__queue-owner") try {
+	if (argv[2] !== "__queue-owner") return false;
+	try {
 		await runQueueOwnerFromEnv(process.env);
-		return;
+		return true;
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		process.stderr.write(`[acpx] queue owner failed: ${message}\n`);
 		process.exit(EXIT_CODES.ERROR);
+		return true;
 	}
-	if (shouldMaybeHandleSkillflag(argv)) {
-		const { findSkillsRoot, maybeHandleSkillflag } = await loadSkillflagModule();
-		await maybeHandleSkillflag(argv, {
-			skillsRoot: findSkillsRoot(import.meta.url),
-			includeBundledSkill: false
+}
+async function maybeHandleSkillflag(argv) {
+	if (!shouldMaybeHandleSkillflag(argv)) return;
+	const { findSkillsRoot, maybeHandleSkillflag } = await loadSkillflagModule();
+	await maybeHandleSkillflag(argv, {
+		skillsRoot: findSkillsRoot(import.meta.url),
+		includeBundledSkill: false
+	});
+}
+function createProgram(requestedJsonStrict) {
+	const program = new Command();
+	program.name("acpx").description("Headless CLI client for the Agent Client Protocol").version(getAcpxVersion()).enablePositionalOptions().showHelpAfterError();
+	if (requestedJsonStrict) program.configureOutput({
+		writeOut: () => {},
+		writeErr: () => {}
+	});
+	return program;
+}
+async function handleProgramParseError(error, requestedOutputPolicy) {
+	if (error instanceof CommanderError) {
+		if (error.code === "commander.helpDisplayed" || error.code === "commander.version") process.exit(EXIT_CODES.SUCCESS);
+		const normalized = normalizeOutputError(error, {
+			defaultCode: "USAGE",
+			origin: "cli"
 		});
+		await emitRequestedError(error, normalized, requestedOutputPolicy);
+		process.exit(exitCodeForOutputErrorCode(normalized.code));
+	}
+	if (error instanceof InterruptedError) process.exit(EXIT_CODES.INTERRUPTED);
+	const normalized = normalizeOutputError(error, { origin: "cli" });
+	await emitRequestedError(error, normalized, requestedOutputPolicy);
+	process.exit(exitCodeForOutputErrorCode(normalized.code));
+}
+async function main(argv = process.argv) {
+	const rawArgs = normalizeLifecycleScriptArgs(argv.slice(2));
+	const normalizedArgv = [
+		argv[0] ?? "node",
+		argv[1] ?? "acpx",
+		...rawArgs
+	];
+	if (await handleQueueOwnerCommand(argv)) return;
+	if (isTopLevelVersionRequest(rawArgs)) {
+		process.stdout.write(`${getAcpxVersion()}\n`);
+		return;
 	}
-	const rawArgs = argv.slice(2);
+	await maybeHandleSkillflag(normalizedArgv);
 	const config = await loadResolvedConfig(detectInitialCwd(rawArgs));
 	const requestedJsonStrict = detectJsonStrict(rawArgs);
 	const requestedOutputPolicy = {
 		...resolveOutputPolicy(detectRequestedOutputFormat(rawArgs, config.format), requestedJsonStrict),
 		suppressReads: rawArgs.some((token) => token === "--suppress-reads")
 	};
-	const program = new Command();
-	program.name("acpx").description("Headless CLI client for the Agent Client Protocol").version(getAcpxVersion()).enablePositionalOptions().showHelpAfterError();
-	if (requestedJsonStrict) program.configureOutput({
-		writeOut: () => {},
-		writeErr: () => {}
-	});
+	const program = createProgram(requestedJsonStrict);
 	addGlobalFlags(program);
 	configurePublicCli({
 		program,
@@ -1599,27 +2283,19 @@ async function main(argv = process.argv) {
 	try {
 		await runWithOutputPolicy(requestedOutputPolicy, async () => {
 			try {
-				await program.parseAsync(argv);
+				await program.parseAsync(normalizedArgv);
 			} catch (error) {
-				if (error instanceof CommanderError) {
-					if (error.code === "commander.helpDisplayed" || error.code === "commander.version") process.exit(EXIT_CODES.SUCCESS);
-					const normalized = normalizeOutputError(error, {
-						defaultCode: "USAGE",
-						origin: "cli"
-					});
-					await emitRequestedError(error, normalized, requestedOutputPolicy);
-					process.exit(exitCodeForOutputErrorCode(normalized.code));
-				}
-				if (error instanceof InterruptedError) process.exit(EXIT_CODES.INTERRUPTED);
-				const normalized = normalizeOutputError(error, { origin: "cli" });
-				await emitRequestedError(error, normalized, requestedOutputPolicy);
-				process.exit(exitCodeForOutputErrorCode(normalized.code));
+				await handleProgramParseError(error, requestedOutputPolicy);
 			}
 		});
 	} finally {
 		flushPerfMetricsCapture();
 	}
 }
+function normalizeLifecycleScriptArgs(rawArgs) {
+	if (rawArgs[0] === "--" && (process.env.npm_lifecycle_event || process.env.npm_lifecycle_script)) return rawArgs.slice(1);
+	return rawArgs;
+}
 //#endregion
 //#region src/cli.ts
 function installBrokenPipeHandler(stream) {
@@ -1628,10 +2304,6 @@ function installBrokenPipeHandler(stream) {
 		throw error;
 	});
 }
-installBrokenPipeHandler(process.stdout);
-installBrokenPipeHandler(process.stderr);
-const queueOwnerArgOverride = buildQueueOwnerArgOverride(fileURLToPath(import.meta.url));
-if (queueOwnerArgOverride) process.env.ACPX_QUEUE_OWNER_ARGS ??= queueOwnerArgOverride;
 function isCliEntrypoint(argv) {
 	const entry = argv[1];
 	if (!entry) return false;
@@ -1642,7 +2314,13 @@ function isCliEntrypoint(argv) {
 		return false;
 	}
 }
-if (isCliEntrypoint(process.argv)) main(process.argv);
+if (isCliEntrypoint(process.argv)) {
+	installBrokenPipeHandler(process.stdout);
+	installBrokenPipeHandler(process.stderr);
+	const queueOwnerArgOverride = buildQueueOwnerArgOverride(fileURLToPath(import.meta.url));
+	if (queueOwnerArgOverride) process.env.ACPX_QUEUE_OWNER_ARGS ??= queueOwnerArgOverride;
+	main(process.argv);
+}
 //#endregion
 export { formatPromptSessionBannerLine, parseAllowedTools, parseMaxTurns, parseTtlSeconds };