@gajae-gateway/cli 0.1.0 → 0.1.2

package/src/main.ts

@@ -1,10 +1,12 @@
 #!/usr/bin/env bun
-import { copyFile, stat } from "node:fs/promises";
+import { Database } from "bun:sqlite";
+import { copyFile, lstat, readFile, stat } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import type {
+	MonitorEventRecord,
 	MonitorRecord,
+	MonitorSpec,
 	OpsCycleResult,
-	OriginRef,
 	WorkJobsResult,
 	WorkRetireResult,
 	WorkRunResult,
@@ -13,7 +15,7 @@ import type {
 	WorkStatusResult,
 	WorkSteerResult,
 } from "@gajae-gateway/protocol";
-import { LOOPBACK_ORIGIN, originKey, parseOriginKey } from "@gajae-gateway/protocol";
+import { LOOPBACK_ORIGIN, originKey } from "@gajae-gateway/protocol";
 import { GajaewayClient } from "@gajae-gateway/sdk";
 import {
 	columnNames,
@@ -24,7 +26,16 @@ import {
 	SESSION_COLUMNS,
 	type SessionListRow,
 } from "./list";
-import { type InstallServicesOptions, installServices, serviceUsage } from "./services";
+import {
+	effectiveRestartState,
+	type LaunchRestartOptions,
+	launchRestartStack,
+	type RunRestartOptions,
+	readRestartReceipt,
+	renderRestartReceipt,
+	runRestartStack,
+} from "./restart-stack";
+import { type InstallServicesOptions, installServices, type ServicePlatform, serviceUsage } from "./services";
 
 export function socketPath(home = process.env.GAJAEWAY_HOME): string {
 	return `${home ?? `${process.env.HOME ?? "~"}/.gajaeway`}/gateway.sock`;
@@ -50,7 +61,7 @@ export const COMMANDS = [
 ] as const;
 
 export const CLI_USAGE =
-	"usage: gajaeway [--socket PATH] status|shutdown|chat|daemon run|sessions list [--json] [--fields a,b,c] [--limit N] [--offset N]|sessions inspect <originKey-or-index>|memory audit|memory search <query>|monitors ...|work run|start <name> [--cwd DIR] [--resume] [--model ID|--preset NAME] [--notify originKey (start only)] <text>|work status <name>|work steer <name> <text>|work retire <name>|work jobs|ops backup <path>|ops cycle [--json]|ops integrity|ops restore <backupPath>|services install|repair --bin-dir DIR [--launch-agents-dir DIR] (work run waits for a response; caller timeout does not end the attempt)";
+	"usage: gajaeway [--socket PATH] status|shutdown|chat|daemon run|sessions list [--json] [--fields a,b,c] [--limit N] [--offset N]|sessions inspect <originKey-or-index>|memory audit|memory search <query>|monitors ... (test <id> [--type T] [--payload J] [--wait[=SECONDS]])|work run|start <name> [--cwd DIR] [--resume] [--model ID|--preset NAME] <text>|work status <name>|work steer <name> <text>|work retire <name>|work jobs|ops backup <path>|ops redeliver <deliveryId>|ops redeliver --since <iso>|ops cycle [--json]|ops integrity|ops restore <backupPath>|ops restart-stack [--status]|services install|repair --bin-dir DIR [--launch-agents-dir DIR] [--unit-dir DIR] [--platform darwin|linux] (work run waits for a response; caller timeout does not end the attempt)";
 
 /** Usage errors exit 2, as `gajaeway-gateway` does; 1 stays a runtime failure. */
 export const USAGE_EXIT_CODE = 2;
@@ -76,6 +87,11 @@ function gatewayHome(): string {
 
 export interface MainOptions {
 	readonly services?: Pick<InstallServicesOptions, "loginPathRunner" | "writeFile">;
+	/** Test seams for `ops restart-stack`; the real path spawns the service manager. */
+	readonly restartStack?: {
+		readonly launch?: Omit<LaunchRestartOptions, "home">;
+		readonly run?: Omit<RunRestartOptions, "home" | "id">;
+	};
 }
 
 export type ServicesAction = "install" | "repair";
@@ -84,6 +100,8 @@ export interface ParsedServicesArgs {
 	readonly action: ServicesAction;
 	readonly binDir: string;
 	readonly launchAgentsDir?: string;
+	readonly unitDir?: string;
+	readonly platform?: ServicePlatform;
 }
 
 export function parseServicesArgs(args: readonly string[]): ParsedServicesArgs {
@@ -91,20 +109,164 @@ export function parseServicesArgs(args: readonly string[]): ParsedServicesArgs {
 	if (action !== "install" && action !== "repair") throw new Error(serviceUsage());
 	let binDir: string | undefined;
 	let launchAgentsDir: string | undefined;
+	let unitDir: string | undefined;
+	let platform: ServicePlatform | undefined;
 	for (let i = 1; i < args.length; i++) {
 		const flag = args[i];
-		if (flag === "--bin-dir" || flag === "--launch-agents-dir") {
+		if (flag === "--bin-dir" || flag === "--launch-agents-dir" || flag === "--unit-dir") {
 			const value = args[++i];
 			if (value === undefined || value.length === 0 || value.startsWith("--"))
 				throw new Error(`${flag} expects a non-empty DIR`);
 			if (flag === "--bin-dir") binDir = value;
+			else if (flag === "--unit-dir") unitDir = value;
 			else launchAgentsDir = value;
+		} else if (flag === "--platform") {
+			const value = args[++i];
+			if (value !== "darwin" && value !== "linux") throw new Error("--platform expects darwin or linux");
+			platform = value;
 		} else throw new Error(`unknown option: ${flag}`);
 	}
 	if (binDir === undefined) throw new Error("services requires --bin-dir DIR");
-	return { action, binDir, ...(launchAgentsDir === undefined ? {} : { launchAgentsDir }) };
+	return {
+		action,
+		binDir,
+		...(launchAgentsDir === undefined ? {} : { launchAgentsDir }),
+		...(unitDir === undefined ? {} : { unitDir }),
+		...(platform === undefined ? {} : { platform }),
+	};
+}
+
+interface ParsedMonitorUpdateArgs {
+	readonly monitorId: string;
+	readonly params: Record<string, unknown>;
+}
+
+const MONITOR_UPDATE_USAGE =
+	"usage: gajaeway monitors update <id> (--json '<partial MonitorSpec JSON>'|--schedule '<cron>' [--enabled true|false]|--enabled true|false [--schedule '<cron>'])";
+
+function parseMonitorUpdateArgs(args: readonly string[]): ParsedMonitorUpdateArgs {
+	const [monitorId, ...options] = args;
+	if (!monitorId || monitorId.startsWith("--") || options.length === 0) throw new Error(MONITOR_UPDATE_USAGE);
+
+	let jsonPatch: Partial<MonitorSpec> | undefined;
+	let schedule: string | undefined;
+	let enabled: boolean | undefined;
+	for (let i = 0; i < options.length; i++) {
+		const option = options[i];
+		if (option === "--json") {
+			const value = options[++i];
+			if (jsonPatch !== undefined || value === undefined || value.startsWith("--"))
+				throw new Error(MONITOR_UPDATE_USAGE);
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(value);
+			} catch {
+				throw new Error(MONITOR_UPDATE_USAGE);
+			}
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error(MONITOR_UPDATE_USAGE);
+			jsonPatch = parsed as Partial<MonitorSpec>;
+		} else if (option === "--schedule") {
+			const value = options[++i];
+			if (schedule !== undefined || !value || value.startsWith("--")) throw new Error(MONITOR_UPDATE_USAGE);
+			schedule = value;
+		} else if (option === "--enabled") {
+			const value = options[++i];
+			if (enabled !== undefined || (value !== "true" && value !== "false")) throw new Error(MONITOR_UPDATE_USAGE);
+			enabled = value === "true";
+		} else throw new Error(MONITOR_UPDATE_USAGE);
+	}
+
+	if (jsonPatch !== undefined && (schedule !== undefined || enabled !== undefined))
+		throw new Error(MONITOR_UPDATE_USAGE);
+	if (jsonPatch !== undefined) return { monitorId, params: { ...jsonPatch, monitorId } };
+	return {
+		monitorId,
+		params: {
+			monitorId,
+			...(schedule === undefined ? {} : { schedule }),
+			...(enabled === undefined ? {} : { enabled }),
+		},
+	};
 }
 
+interface ParsedMonitorTestArgs {
+	readonly monitorId: string;
+	readonly eventType?: string;
+	readonly payload: unknown;
+	readonly waitSeconds?: number;
+}
+
+const MONITOR_TEST_USAGE = "usage: gajaeway monitors test <id> [--type T] [--payload J] [--wait[=SECONDS]]";
+const MONITOR_WAIT_ERROR = `${MONITOR_TEST_USAGE}\n--wait expects a finite non-negative integer up to 86400`;
+
+function parseMonitorTestArgs(args: readonly string[]): ParsedMonitorTestArgs {
+	const [monitorId, ...flags] = args;
+	if (!monitorId || monitorId.startsWith("--")) throw new Error(MONITOR_TEST_USAGE);
+	let eventType: string | undefined;
+	let payload: unknown = {};
+	let waitSeconds: number | undefined;
+	const seen = new Set<string>();
+	for (let i = 0; i < flags.length; i++) {
+		const flag = flags[i];
+		if (flag === "--type" || flag === "--payload") {
+			if (seen.has(flag)) throw new Error(`${MONITOR_TEST_USAGE}\nduplicate ${flag}`);
+			seen.add(flag);
+			const value = flags[++i];
+			if (value === undefined || value.length === 0 || value.startsWith("--"))
+				throw new Error(`${MONITOR_TEST_USAGE}\n${flag} requires a value`);
+			if (flag === "--type") eventType = value;
+			else payload = JSON.parse(value);
+		} else if (flag === "--wait" || flag.startsWith("--wait=")) {
+			if (seen.has("--wait")) throw new Error(`${MONITOR_TEST_USAGE}\nduplicate --wait`);
+			seen.add("--wait");
+			const value = flag === "--wait" ? undefined : flag.slice("--wait=".length);
+			if (value === undefined) waitSeconds = 30;
+			else {
+				if (!/^\d+$/.test(value)) throw new Error(MONITOR_WAIT_ERROR);
+				const seconds = Number(value);
+				if (!Number.isFinite(seconds) || !Number.isInteger(seconds) || seconds > 86_400)
+					throw new Error(MONITOR_WAIT_ERROR);
+				waitSeconds = seconds;
+			}
+		} else throw new Error(`${MONITOR_TEST_USAGE}\nunknown argument: ${flag}`);
+	}
+	return {
+		monitorId,
+		...(eventType === undefined ? {} : { eventType }),
+		payload,
+		...(waitSeconds === undefined ? {} : { waitSeconds }),
+	};
+}
+
+const TERMINAL_MONITOR_STAGES = new Set(["delivered", "authored_no_delivery", "failed", "failed_no_retry"]);
+
+function waitForMonitorStage(client: GajaewayClient, eventId: string, timeoutSeconds: number): Promise<string> {
+	return new Promise((resolve) => {
+		let stage = "admitted";
+		let settled = false;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let unsubscribe: (() => void) | undefined;
+		const finish = (): void => {
+			if (settled) return;
+			settled = true;
+			if (timer !== undefined) clearTimeout(timer);
+			unsubscribe?.();
+			resolve(stage);
+		};
+		unsubscribe = client.on("monitor.event", (payload) => {
+			if (typeof payload !== "object" || payload === null) return;
+			const event = payload as Partial<MonitorEventRecord>;
+			if (event.eventId !== eventId || typeof event.stage !== "string") return;
+			stage = event.stage;
+			if (TERMINAL_MONITOR_STAGES.has(stage)) finish();
+		});
+		// GajaewayClient.on may synchronously replay an event held before the
+		// monitor.test response; if that event was terminal, clean up the now
+		// installed listener rather than starting the timeout.
+		if (settled) unsubscribe();
+		else timer = setTimeout(finish, timeoutSeconds * 1000);
+	});
+}
 /**
  * Operator runtime-cycle view (`gajaeway ops cycle`).
  *
@@ -132,10 +294,23 @@ export function renderCycle(cycle: OpsCycleResult): string[] {
 	lines.push(
 		`memory: queued=${cycle.memoryIntents.queued} written=${cycle.memoryIntents.written} committed=${cycle.memoryIntents.committed} receipted=${cycle.memoryIntents.receipted} quarantined=${cycle.memoryIntents.quarantined}${cycle.memoryClosing ? " (closing)" : ""}`,
 	);
+	if (cycle.agentDisk) {
+		const { path, freeBytes, totalBytes } = cycle.agentDisk;
+		const gib = (bytes: number) => (bytes / 1024 ** 3).toFixed(1);
+		lines.push(
+			freeBytes === null || totalBytes === null
+				? `agent_disk: ${path} unobservable`
+				: `agent_disk: ${path} free=${gib(freeBytes)}GiB total=${gib(totalBytes)}GiB`,
+		);
+	}
 	// Always rendered: an empty subsystem must be distinguishable from an absent one.
 	lines.push(
 		`monitors: ${cycle.monitorEvents.length ? cycle.monitorEvents.map((m) => `${m.stage}=${m.count}`).join(" ") : "none"}`,
 	);
+	if (cycle.monitorAuthoringLost.length > 0)
+		lines.push(
+			`monitor authoring lost: ${cycle.monitorAuthoringLost.map((m) => `${m.eventType}=${m.consecutive} (last ${m.lastFiredAt})`).join(" ")}`,
+		);
 	if (cycle.sessions.length > 0) {
 		lines.push("sessions:");
 		lines.push("INDEX  ORIGIN                                      EPOCH  SESSION      PENDING  UNSETTLED  OLDEST");
@@ -159,6 +334,87 @@ export function cycleExitCode(cycle: OpsCycleResult): number {
 	return cycle.gates.length > 0 ? 1 : 0;
 }
 
+/**
+ * The same acceptance the gateway applies at boot (`PRAGMA integrity_check`
+ * must answer `ok`), run read-only against the backup before it replaces
+ * anything. A 16-byte header match is not a database: a truncated or
+ * bit-flipped file passes it, gets copied into place, and the next boot
+ * fails while the restore already reported success.
+ *
+ * An empty file is also refused: SQLite treats a zero-length file as a valid
+ * empty database and `integrity_check` answers `ok` for it, but restoring it
+ * would boot a gateway with every table freshly created and nothing in them.
+ *
+ * Opening a WAL-mode backup read-only may leave empty `-wal`/`-shm` sidecars
+ * next to the backup; `ops backup` writes delete-mode files, which gain none.
+ */
+export function verifyBackupIntegrity(backupPath: string): void {
+	let database: Database;
+	try {
+		database = new Database(backupPath, { readonly: true });
+	} catch (error) {
+		throw new Error(
+			`Backup is not readable: ${backupPath} (${error instanceof Error ? error.message : String(error)})`,
+		);
+	}
+	let detail: string;
+	let pageCount: number;
+	try {
+		pageCount = database.query<{ page_count: number }, []>("PRAGMA page_count").get()?.page_count ?? 0;
+		detail =
+			database.query<{ integrity_check: string }, []>("PRAGMA integrity_check").get()?.integrity_check ?? "unknown";
+	} catch (error) {
+		throw new Error(
+			`Backup is not a readable SQLite database: ${backupPath} (${error instanceof Error ? error.message : String(error)})`,
+		);
+	} finally {
+		database.close();
+	}
+	if (pageCount === 0) throw new Error(`Backup is an empty SQLite database: ${backupPath}`);
+	if (detail !== "ok") throw new Error(`Backup failed SQLite integrity_check: ${backupPath} (${detail})`);
+}
+
+/**
+ * The database the gateway actually opens: `config.json` `dbPath` when set,
+ * otherwise `<home>/gateway.db` — the same file-based resolution as the
+ * gateway's `loadConfig`. An absent `config.json` means defaults, exactly as
+ * at boot. A present-but-unreadable one (EACCES, EISDIR, or a dangling symlink,
+ * which reports ENOENT while the entry exists) refuses the restore instead of
+ * guessing, as boot refuses to start: copying a backup over the wrong file
+ * reports success while the live database stays broken.
+ *
+ * `schemaVersion` is deliberately not checked: `dbPath` is a version-independent
+ * string, and disaster recovery must not be blocked by an unrelated schema bump.
+ */
+export async function restoreTargetPath(home = gatewayHome()): Promise<string> {
+	const configPath = join(home, "config.json");
+	let raw: string | undefined;
+	try {
+		raw = await readFile(configPath, "utf8");
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		const entryExists = await lstat(configPath).then(
+			() => true,
+			() => false,
+		);
+		if (code !== "ENOENT" || entryExists) throw new Error(`Cannot read ${configPath}; refusing restore.`);
+	}
+	if (raw === undefined) return join(home, "gateway.db");
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new Error(`Cannot parse ${configPath}; refusing restore.`);
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+		throw new Error(`Invalid configuration ${configPath}: config must be an object; refusing restore.`);
+	const dbPath = (parsed as { dbPath?: unknown }).dbPath;
+	if (dbPath === undefined) return join(home, "gateway.db");
+	if (typeof dbPath !== "string" || dbPath.length === 0)
+		throw new Error(`Invalid configuration ${configPath}: dbPath must be a non-empty string; refusing restore.`);
+	return dbPath;
+}
+
 export async function restoreDatabase(socket: string, backupPath: string): Promise<void> {
 	if (!isAbsolute(backupPath)) throw new Error("ops restore requires an absolute backup path");
 	try {
@@ -169,15 +425,8 @@ export async function restoreDatabase(socket: string, backupPath: string): Promi
 		if ((error as NodeJS.ErrnoException).code !== "ENOENT")
 			throw new Error(`Cannot verify gateway socket ${socket}; refusing restore.`);
 	}
-	let header: Uint8Array;
-	try {
-		header = new Uint8Array(await Bun.file(backupPath).slice(0, 16).arrayBuffer());
-	} catch {
-		throw new Error(`Backup is not readable: ${backupPath}`);
-	}
-	if (new TextDecoder().decode(header) !== "SQLite format 3\u0000")
-		throw new Error(`Backup is not a SQLite database: ${backupPath}`);
-	const databasePath = join(gatewayHome(), "gateway.db");
+	verifyBackupIntegrity(backupPath);
+	const databasePath = await restoreTargetPath();
 	const preservedPath = `${databasePath}.pre-restore-${new Date().toISOString().replace(/[:.]/g, "-")}`;
 	await copyFile(databasePath, preservedPath);
 	await copyFile(backupPath, databasePath);
@@ -186,6 +435,8 @@ export async function restoreDatabase(socket: string, backupPath: string): Promi
 	console.log(`Restored backup to: ${databasePath}`);
 }
 
+const CHAT_TURN_TIMEOUT_MS = 30 * 60_000;
+
 async function chat(socket: string): Promise<void> {
 	let client: GajaewayClient;
 	try {
@@ -206,12 +457,15 @@ async function chat(socket: string): Promise<void> {
 			console.error("(message was not engaged)");
 			return;
 		}
+		// The gateway's own request wait is 30 minutes; a max-effort reasoning
+		// turn routinely runs past two. Match the server so the REPL does not
+		// abandon a turn the gateway is still delivering.
 		await new Promise<void>((resolve) => {
 			const timer = setTimeout(() => {
 				turnWaiters.delete(turnId);
-				console.error("(turn timed out after 120s)");
+				console.error(`(turn timed out after ${CHAT_TURN_TIMEOUT_MS / 60_000}m)`);
 				resolve();
-			}, 120_000);
+			}, CHAT_TURN_TIMEOUT_MS);
 			turnWaiters.set(turnId, () => {
 				clearTimeout(timer);
 				turnWaiters.delete(turnId);
@@ -340,9 +594,51 @@ export async function main(args = process.argv.slice(2), options: MainOptions =
 					await restoreDatabase(parsed.socket, path);
 					break;
 				}
+				if (command === "restart-stack") {
+					// Deliberately socket-free: the reason to run this is a gateway that
+					// has to come back, so it must not need the gateway to answer first.
+					// It also runs detached: restarting the gateway kills a persona turn that
+					// invoked it, which must not end the sequence half-applied (issue #54).
+					const usage = "usage: gajaeway ops restart-stack [--status]";
+					const home = gatewayHome();
+					const flag = parsed.rest[1];
+					if (flag === "--run" && parsed.rest.length === 3 && parsed.rest[2]) {
+						const receipt = await runRestartStack({
+							...options.restartStack?.run,
+							home,
+							id: parsed.rest[2],
+						});
+						for (const line of renderRestartReceipt(receipt)) console.log(line);
+						if (receipt.state !== "ok") process.exitCode = 1;
+					} else if (flag === "--status" && parsed.rest.length === 2) {
+						const receipt = await readRestartReceipt(home);
+						if (receipt === undefined) throw new Error("no restart-stack receipt");
+						for (const line of renderRestartReceipt(receipt)) console.log(line);
+						// Only a completed, verified sequence exits 0; queued or running is not yet success.
+						if (effectiveRestartState(receipt) !== "ok") process.exitCode = 1;
+					} else if (parsed.rest.length === 1) {
+						const { receipt, supervisorPid } = await launchRestartStack({ ...options.restartStack?.launch, home });
+						console.log(`restart-stack ${receipt.id}: queued (supervisor pid ${supervisorPid})`);
+						console.log("read the outcome with: gajaeway ops restart-stack --status");
+					} else throw new Error(usage);
+					break;
+				}
+				let redeliverParams: { deliveryId: string } | { since: string } | undefined;
+				if (command === "redeliver") {
+					if (parsed.rest.length === 2 && path && path !== "--since") redeliverParams = { deliveryId: path };
+					else if (
+						parsed.rest.length === 3 &&
+						path === "--since" &&
+						parsed.rest[2] &&
+						Number.isFinite(Date.parse(parsed.rest[2]))
+					)
+						redeliverParams = { since: parsed.rest[2] };
+					else throw new Error("usage: gajaeway ops redeliver <deliveryId>|--since <iso>");
+				}
 				const client = await GajaewayClient.connectSocket(parsed.socket);
 				try {
 					if (command === "backup" && path) console.log(JSON.stringify(await client.request("ops.backup", { path })));
+					else if (redeliverParams) console.log(JSON.stringify(await client.request("ops.redeliver", redeliverParams)));
 					else if (command === "integrity") console.log(JSON.stringify(await client.request("ops.integrity")));
 					else if (command === "cycle") {
 						const cycle = await client.opsCycle();
@@ -352,7 +648,10 @@ export async function main(args = process.argv.slice(2), options: MainOptions =
 						// Fail-closed: a gated/degraded cycle exits non-zero even though the
 						// request itself succeeded, so scripts can never read it as healthy.
 						process.exitCode = cycleExitCode(cycle);
-					} else throw new Error("usage: gajaeway ops backup <path>|cycle [--json]|integrity|restore <backupPath>");
+					} else
+						throw new Error(
+							"usage: gajaeway ops backup <path>|redeliver <deliveryId>|redeliver --since <iso>|cycle [--json]|integrity|restore <backupPath>|restart-stack [--status]",
+						);
 				} finally {
 					await client.close();
 				}
@@ -384,13 +683,16 @@ export async function main(args = process.argv.slice(2), options: MainOptions =
 				break;
 			}
 			case "monitors": {
-				const listOptions =
-					parsed.rest[0] === "list" ? parseListOptions(parsed.rest.slice(1), MONITOR_COLUMNS) : undefined;
+				const [command, ...args] = parsed.rest;
+				const listOptions = command === "list" ? parseListOptions(args, MONITOR_COLUMNS) : undefined;
+				const update = command === "update" ? parseMonitorUpdateArgs(args) : undefined;
+				const monitorTest = command === "test" ? parseMonitorTestArgs(args) : undefined;
 				const client = await GajaewayClient.connectSocket(parsed.socket);
 				try {
-					const [command, ...args] = parsed.rest;
 					if (command === "add" && args[0] === "--json" && args[1])
 						console.log(JSON.stringify(await client.request("monitor.add", JSON.parse(args[1]))));
+					else if (command === "update" && update)
+						console.log(JSON.stringify(await client.request<{ monitorId: string }>("monitor.update", update.params)));
 					else if (command === "list") {
 						const options = listOptions as ListOptions;
 						const result = await client.request<{ monitors: MonitorRecord[] }>("monitor.list");
@@ -403,25 +705,20 @@ export async function main(args = process.argv.slice(2), options: MainOptions =
 						console.log(JSON.stringify(await client.request("monitor.inspect", { monitorId: args[0] })));
 					else if (command === "remove" && args[0])
 						console.log(JSON.stringify(await client.request("monitor.remove", { monitorId: args[0] })));
-					else if (command === "test" && args[0]) {
-						let eventType: string | undefined;
-						let payload: unknown = {};
-						for (let i = 1; i < args.length; i++) {
-							if (args[i] === "--type") eventType = args[++i];
-							else if (args[i] === "--payload") payload = JSON.parse(args[++i] ?? "");
+					else if (command === "test" && monitorTest) {
+						const result = await client.request<{ eventId: string }>("monitor.test", {
+							monitorId: monitorTest.monitorId,
+							...(monitorTest.eventType === undefined ? {} : { eventType: monitorTest.eventType }),
+							payload: monitorTest.payload,
+						});
+						if (monitorTest.waitSeconds === undefined) console.log(JSON.stringify(result));
+						else {
+							const stage = await waitForMonitorStage(client, result.eventId, monitorTest.waitSeconds);
+							console.log(JSON.stringify({ eventId: result.eventId, stage }));
 						}
-						console.log(
-							JSON.stringify(
-								await client.request("monitor.test", {
-									monitorId: args[0],
-									...(eventType ? { eventType } : {}),
-									payload,
-								}),
-							),
-						);
 					} else
 						throw new Error(
-							`usage: gajaeway monitors add --json '<MonitorSpec json>'|list [--json] [--fields ${columnNames(MONITOR_COLUMNS).join(",")}] [--limit N] [--offset N]|inspect <id>|remove <id>|test <id> [--type T] [--payload J]`,
+							`usage: gajaeway monitors add --json '<MonitorSpec json>'|update <id> (--json '<partial MonitorSpec JSON>'|--schedule '<cron>' [--enabled true|false]|--enabled true|false [--schedule '<cron>'])|list [--json] [--fields ${columnNames(MONITOR_COLUMNS).join(",")}] [--limit N] [--offset N]|inspect <id>|remove <id>|test <id> [--type T] [--payload J] [--wait[=SECONDS]]`,
 						);
 				} finally {
 					await client.close();
@@ -431,7 +728,7 @@ export async function main(args = process.argv.slice(2), options: MainOptions =
 			case "work": {
 				const [command, ...args] = parsed.rest;
 				const usage =
-					'usage: gajaeway work run|start <name> [--cwd DIR] [--resume] [--model ID|--preset NAME] [--notify originKey (start only)] "<task text>"|status <name>|steer <name> <text>|retire <name>|jobs';
+					'usage: gajaeway work run|start <name> [--cwd DIR] [--resume] [--model ID|--preset NAME] "<task text>"|status <name>|steer <name> <text>|retire <name>|jobs';
 				if (command === "status" || command === "steer") {
 					const name = args[0];
 					const text = args.slice(1).join(" ").trim();
@@ -475,8 +772,22 @@ export async function main(args = process.argv.slice(2), options: MainOptions =
 								const state = job.quarantined
 									? `HELD: quarantined reason=${job.reason} historical_state=${job.state}`
 									: job.state;
+								// HEAD is the progress signal that survives a dead op (issue #67).
+								const head = job.last_commit
+									? `${job.last_commit.sha.slice(0, 7)}@${job.last_commit.committed_at} ${JSON.stringify(job.last_commit.subject)}`
+									: "-";
 								console.log(
-									`${name} ${state} session=${job.session_id || "-"} last=${job.last_activity_at || "-"} ${job.worktree_path}`,
+									`${name} ${state} session=${job.session_id || "-"} accepted=${job.accepted_at || "-"} op=${job.attempt?.op_ref || "-"} last=${job.last_activity_at || "-"} head=${head} ${job.worktree_path}${
+										job.reports &&
+										(
+											job.reports.pending !== 0 ||
+												job.reports.claimed !== 0 ||
+												job.reports.held !== 0 ||
+												job.reports.undeliverable !== 0
+										)
+											? ` reports=p:${job.reports.pending} c:${job.reports.claimed} h:${job.reports.held} u:${job.reports.undeliverable}`
+											: ""
+									}`,
 								);
 							}
 						}
@@ -490,23 +801,15 @@ export async function main(args = process.argv.slice(2), options: MainOptions =
 				let cwd: string | undefined;
 				let resume = false;
 				let model: string | { preset: string } | undefined;
-				let notify: OriginRef | undefined;
 				const textParts: string[] = [];
 				for (let i = 1; i < args.length; i++) {
 					const arg = args[i];
-					if (arg === "--cwd" || arg === "--model" || arg === "--preset" || arg === "--notify") {
+					if (arg === "--cwd" || arg === "--model" || arg === "--preset") {
 						const value = args[++i];
 						if (!value?.trim() || value.startsWith("--")) throw new Error(usage);
 						if (arg === "--cwd") {
 							if (cwd !== undefined || !isAbsolute(value)) throw new Error(usage);
 							cwd = value;
-						} else if (arg === "--notify") {
-							if (command !== "start" || notify !== undefined) throw new Error(usage);
-							try {
-								notify = parseOriginKey(value);
-							} catch {
-								throw new Error(`${usage}\ninvalid --notify originKey`);
-							}
 						} else {
 							if (model !== undefined) throw new Error(`${usage}\n--model and --preset are mutually exclusive`);
 							model = arg === "--preset" ? { preset: value } : value;
@@ -523,13 +826,14 @@ export async function main(args = process.argv.slice(2), options: MainOptions =
 					requestTimeoutMs: command === "run" ? 3_600_000 : 120_000,
 				});
 				try {
+					const callerSessionId = process.env.GJC_SESSION_ID?.trim();
 					const params: WorkStartParams = {
 						name,
 						text,
 						...(cwd ? { cwd } : {}),
 						...(resume ? { resume: true } : {}),
 						...(model === undefined ? {} : { model }),
-						...(notify === undefined ? {} : { notify }),
+						...(callerSessionId ? { callerSessionId } : {}),
 					};
 					if (command === "start") {
 						const result = await client.request<WorkStartResult>("work.start", params);
@@ -558,10 +862,13 @@ export async function main(args = process.argv.slice(2), options: MainOptions =
 				const written = await installServices({
 					binDir: service.binDir,
 					...(service.launchAgentsDir === undefined ? {} : { launchAgentsDir: service.launchAgentsDir }),
+					...(service.unitDir === undefined ? {} : { unitDir: service.unitDir }),
+					...(service.platform === undefined ? {} : { platform: service.platform }),
 					env: process.env,
 					...options.services,
 				});
-				console.log(`services ${service.action}: wrote ${written.length} LaunchAgent plists`);
+				console.log(`services ${service.action}: wrote ${written.length} service definitions`);
+				for (const definition of written) console.log(definition);
 				break;
 			}
 			default: