@danypops/papyrus 0.48.0 → 0.49.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.48.0",
+  "version": "0.49.1",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "main": "./src/index.ts",
@@ -35,7 +35,7 @@
   "dependencies": {
     "@danypops/vehicle-client": "^0.6.1",
     "@danypops/vehicle-core": "^0.12.3",
-    "@danypops/vehicle-server": "^0.18.1",
+    "@danypops/vehicle-server": "^0.19.0",
     "@stricli/core": "^1.3.0"
   }
 }

package/src/cli/daemon-command.ts

@@ -0,0 +1,48 @@
+import type { DaemonDiagnosis } from "@danypops/vehicle-server/daemon-lifecycle";
+import type { CommandContext } from "@stricli/core";
+import { buildApplication, buildCommand, buildRouteMap } from "@stricli/core";
+import { runStricliToString } from "./stricli-run.ts";
+
+export interface DaemonDiagnoseClient {
+	diagnose(): Promise<DaemonDiagnosis>;
+}
+
+interface DaemonContext extends CommandContext {
+	readonly client: DaemonDiagnoseClient;
+	readonly json: boolean;
+}
+
+function renderHistoryLine(event: DaemonDiagnosis["history"][number]): string {
+	const reason = event.reason ? ` (${event.reason})` : "";
+	return `${event.at}  ${event.type}${reason}  pid=${event.pid} instance=${event.instanceId}`;
+}
+
+const diagnoseCommand = buildCommand({
+	func: async function (this: DaemonContext) {
+		const diagnosis = await this.client.diagnose();
+		if (this.json) {
+			this.process.stdout.write(JSON.stringify(diagnosis));
+			return;
+		}
+		const lines = [
+			`instance ${diagnosis.instanceId} (pid ${diagnosis.pid}, ${diagnosis.provenance}), started ${diagnosis.startedAt}`,
+			"",
+			"recent history:",
+			...(diagnosis.history.length === 0 ? ["  (none)"] : diagnosis.history.map((event) => `  ${renderHistoryLine(event)}`)),
+		];
+		this.process.stdout.write(lines.join("\n"));
+	},
+	parameters: { flags: {} },
+	docs: { brief: "Show this daemon's identity and recent start/stop/already_running history" },
+});
+
+const app = buildApplication(buildRouteMap({ routes: { diagnose: diagnoseCommand }, docs: { brief: "Daemon operations" } }), {
+	name: "daemon",
+	scanner: { caseStyle: "allow-kebab-for-camel" },
+});
+
+export async function runDaemonCli(args: string[], client: DaemonDiagnoseClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional = args.filter((arg) => arg !== "--json");
+	return runStricliToString(app, positional, { client, json });
+}

package/src/cli.ts

@@ -4,6 +4,7 @@ import { copyFileSync, existsSync, readFileSync, renameSync, unlinkSync, writeFi
 import { fileURLToPath } from "node:url";
 import { createNodeServiceInstallDeps, generateSystemdUnit, installUserService, type ServiceSpec } from "@danypops/vehicle-server/service";
 import { runArtifactCli } from "./cli/artifact-command.ts";
+import { runDaemonCli } from "./cli/daemon-command.ts";
 import { runDiscussCli } from "./cli/discuss-command.ts";
 import { runDocsCli } from "./cli/docs-command.ts";
 import { runGatesCli } from "./cli/gates-command.ts";
@@ -206,7 +207,7 @@ function usage(): never {
 	process.exit(2);
 }
 
-export { runMigrationCli };
+export { runDaemonCli, runMigrationCli };
 
 function readIdMap(sidecarPath: string): IdMigrationPlan {
 	const raw = JSON.parse(readFileSync(sidecarPath, "utf8")) as { idMap: Record<string, string> };
@@ -366,7 +367,7 @@ export {
 export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
 	const [command, action] = args;
 	if (command === "serve") {
-		serveMain();
+		await serveMain();
 		return;
 	}
 	if (command === "tasks") {
@@ -404,6 +405,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runMigrationCli(args.slice(1), client));
 		return;
 	}
+	if (command === "daemon") {
+		const client = await connectPapyrusClient();
+		console.log(await runDaemonCli(args.slice(1), client));
+		return;
+	}
 	if (command === "migrate-ids") {
 		console.log(runIdMigrationCli(args.slice(1)));
 		return;

package/src/client.ts

@@ -7,6 +7,7 @@ import {
 	spawnDetachedDaemon,
 } from "@danypops/vehicle-client/daemon-client";
 import { createLiveVersionExpectation } from "@danypops/vehicle-client/version";
+import type { DaemonDiagnosis } from "@danypops/vehicle-server/daemon-lifecycle";
 import { DAEMON_CLIENT_TIMEOUT_MS, DAEMON_DIR_ENV, DAEMON_PROBE_TIMEOUT_MS } from "./constants.ts";
 import { type DaemonHandle, daemonStateDir, readDaemonHandle } from "./daemon/daemon-state.ts";
 import type { OperationName, SchemaState } from "./service.ts";
@@ -50,6 +51,11 @@ export class PapyrusClient {
 		return this.request("/health");
 	}
 
+	/** Backed by GET /daemon/diagnose -- see service.ts's createApp and vehicle-server's daemon-lifecycle.ts. */
+	diagnose(): Promise<DaemonDiagnosis> {
+		return this.request("/daemon/diagnose");
+	}
+
 	async operations(): Promise<OperationName[]> {
 		const body = await this.request<{ operations: OperationName[] }>("/api/v1/ops");
 		return body.operations;

package/src/constants.ts

@@ -4,6 +4,7 @@ export const DAEMON_PORT_FILE = "port";
 export const DAEMON_TOKEN_FILE = "token";
 /** vehicle-server's own {host,port,pid} handle format -- read by Armada's readiness probe once Papyrus is service-installed, see cli.ts's papyrusServiceSpec. */
 export const DAEMON_HANDLE_FILE = "vehicle-handle.json";
+export const DAEMON_LIFECYCLE_FILE = "lifecycle.json";
 export const DAEMON_CLIENT_TIMEOUT_MS = 15_000;
 export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";

package/src/daemon/daemon-state.ts

@@ -3,7 +3,14 @@ import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { LOOPBACK_HOST, removeDaemonHandle, writeDaemonHandle } from "@danypops/vehicle-server/paths";
-import { DAEMON_DIR_ENV, DAEMON_HANDLE_FILE, DAEMON_HOST, DAEMON_PORT_FILE, DAEMON_TOKEN_FILE } from "../constants.ts";
+import {
+	DAEMON_DIR_ENV,
+	DAEMON_HANDLE_FILE,
+	DAEMON_HOST,
+	DAEMON_LIFECYCLE_FILE,
+	DAEMON_PORT_FILE,
+	DAEMON_TOKEN_FILE,
+} from "../constants.ts";
 
 export interface DaemonHandle {
 	baseUrl: string;
@@ -48,6 +55,11 @@ export function vehicleHandlePath(dir: string): string {
 	return join(dir, DAEMON_HANDLE_FILE);
 }
 
+/** Where the structured daemon lifecycle event log (@danypops/vehicle-server's daemon-lifecycle.ts) persists start/stop/already_running history across restarts -- see daemon.ts's diagnose wiring. */
+export function lifecyclePath(dir: string): string {
+	return join(dir, DAEMON_LIFECYCLE_FILE);
+}
+
 /** vehicle-server's own {host,port,pid} handle format, distinct from this file's port/token pair -- Armada's readiness probe (createHandleReadinessProbe) reads exactly this shape. */
 export function writeVehicleHandle(dir: string, port: number, pid: number = process.pid): void {
 	writeDaemonHandle(vehicleHandlePath(dir), { host: LOOPBACK_HOST, port, pid });

package/src/daemon/daemon.ts

@@ -1,4 +1,8 @@
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
+import { createNodeAtomicJsonFsAdapter } from "@danypops/vehicle-server/atomic-json";
+import { readLaunchProvenance } from "@danypops/vehicle-server/daemon";
+import { diagnoseDaemon, openDaemonLifecycleLog } from "@danypops/vehicle-server/daemon-lifecycle";
 import { acquireDaemonLock, releaseDaemonLock } from "@danypops/vehicle-server/paths";
 import { PushChannel } from "@danypops/vehicle-server/push-channel";
 import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, dbPath, WAL_CHECKPOINT_INTERVAL_MS } from "../constants.ts";
@@ -8,6 +12,7 @@ import {
 	clearDaemonPort,
 	clearVehicleHandle,
 	daemonStateDir,
+	lifecyclePath,
 	loadOrCreateToken,
 	writeDaemonPort,
 	writeVehicleHandle,
@@ -35,14 +40,26 @@ const TASK_READ_ONLY_OPERATIONS = new Set([
 ]);
 
 /** Start the supervised, long-running Papyrus service. */
-export function serveMain(): void {
+export async function serveMain(): Promise<void> {
 	const stateDir = daemonStateDir();
 	const lockPath = join(stateDir, "daemon.lock");
+	const instanceId = randomUUID();
+	const provenance = readLaunchProvenance();
+	const lifecycleLog = openDaemonLifecycleLog({ path: lifecyclePath(stateDir), fs: createNodeAtomicJsonFsAdapter() });
+	const recordLifecycle = async (type: "started" | "already_running" | "stopped", reason?: string): Promise<void> => {
+		try {
+			await lifecycleLog.record({ instanceId, pid: process.pid, type, provenance, reason });
+		} catch (error) {
+			logEvent("error", "lifecycle_log_record_failed", { message: error instanceof Error ? error.message : String(error) });
+		}
+	};
 	const lock = acquireDaemonLock(lockPath);
 	if (!lock.acquired) {
 		logEvent("info", "already_running", { holderPid: lock.holderPid });
+		await recordLifecycle("already_running", lock.holderPid === null ? undefined : `holder pid ${lock.holderPid}`);
 		return;
 	}
+	const startedAt = new Date().toISOString();
 	const token = loadOrCreateToken(stateDir);
 	const service = createPapyrusService(dbPath());
 	const pushChannel = new PushChannel({ token });
@@ -55,6 +72,7 @@ export function serveMain(): void {
 			}
 		},
 		logger: vehicleLogger(),
+		diagnose: () => diagnoseDaemon({ lifecycleLog, current: { instanceId, pid: process.pid, startedAt, provenance } }),
 	});
 	const server = Bun.serve({
 		hostname: DAEMON_HOST,
@@ -110,7 +128,7 @@ export function serveMain(): void {
 		}
 	}, DB_OPTIMIZE_INTERVAL_MS);
 	let stopping = false;
-	const shutdown = () => {
+	const shutdown = (signal: string) => {
 		if (stopping) return;
 		stopping = true;
 		clearInterval(checkpointTimer);
@@ -123,12 +141,13 @@ export function serveMain(): void {
 		service.close();
 		// .finally() re-throws rather than handling a rejection -- catching it first turns a bare
 		// unhandled-rejection warning into a real, queryable shutdown-failure log line.
-		void server
-			.stop(true)
+		void recordLifecycle("stopped", signal)
+			.then(() => server.stop(true))
 			.catch((error) => logEvent("error", "server_stop_failed", { message: error instanceof Error ? error.message : String(error) }))
 			.finally(() => process.exit(0));
 	};
-	process.on("SIGINT", shutdown);
-	process.on("SIGTERM", shutdown);
+	process.on("SIGINT", () => shutdown("SIGINT"));
+	process.on("SIGTERM", () => shutdown("SIGTERM"));
 	logEvent("info", "listening", { host: DAEMON_HOST, port: server.port });
+	await recordLifecycle("started");
 }

package/src/ops.ts

@@ -599,22 +599,34 @@ function readBoundedGateFile(path: string): string {
 	return readFileSync(path, "utf-8") as string;
 }
 
-/** Shared by the sync and async process-gate runners so "test" is never a second, independently
- * maintained copy of "command"'s own command-template/timeout selection. */
+/**
+ * Shared by the sync and async process-gate runners so "test" is never a second, independently
+ * maintained copy of "command"'s own command-template selection.
+ *
+ * "test" runs `gate.target` verbatim, exactly like "command" -- the only real difference is a
+ * more generous default timeout (GATE_TEST_TIMEOUT_MS vs GATE_COMMAND_TIMEOUT_MS), since a test
+ * suite routinely runs longer than an arbitrary command. It previously wrapped target in
+ * `npx vitest run ${target} --reporter=dot`, silently wrong for every real consumer in this
+ * ecosystem (all Bun-native, none use vitest): a target that was itself a full command (e.g.
+ * `bun test path/to.test.ts`, exactly what every existing gate/checklist example here has always
+ * shown) got parsed by vitest as three separate positional args, triggering vitest's own broad
+ * discovery across the whole repo instead of running the intended command at all -- a real
+ * incident (task ab1463e2) that produced an unrelated multi-suite vitest failure cascade instead
+ * of the actual target ever running.
+ */
 function processGateCommand(gate: Gate): { command: string; timeout: number } {
-	if (gate.type === "test")
-		return { command: `npx vitest run ${gate.target} --reporter=dot`, timeout: gate.timeoutMs ?? GATE_TEST_TIMEOUT_MS };
+	if (gate.type === "test") return { command: gate.target, timeout: gate.timeoutMs ?? GATE_TEST_TIMEOUT_MS };
 	return { command: gate.target, timeout: gate.timeoutMs ?? GATE_COMMAND_TIMEOUT_MS };
 }
 
 /**
  * spawnSync + manual stdout/stderr concatenation, not execSync: execSync's return value is stdout
- * only. Many real commands (bun test's own per-test lines and its pass/fail summary among them, and
- * vitest's own "test" gate output) write their actual output to stderr, so an execSync-based match
- * against gate.expect saw only the first line of a banner and never the result -- every such gate
- * failed regardless of whether the command actually passed. This one function now serves both
- * "command" and "test" gates; previously "test" was a second, separately-maintained execSync path
- * that never checked gate.expect at all.
+ * only. Many real commands (bun test's own per-test lines and its pass/fail summary among them)
+ * write their actual output to stderr, so an execSync-based match against gate.expect saw only the
+ * first line of a banner and never the result -- every such gate failed regardless of whether the
+ * command actually passed. This one function now serves both "command" and "test" gates;
+ * previously "test" was a second, separately-maintained execSync path that never checked
+ * gate.expect at all.
  */
 function runProcessGateSync(gate: Gate, cwd?: string): GateResult {
 	const { spawnSync } = require_("node:child_process");

package/src/service.ts

@@ -1,5 +1,6 @@
 import { VehicleError } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
+import type { DaemonDiagnosis } from "@danypops/vehicle-server/daemon-lifecycle";
 import { createVehicleHttpApp } from "@danypops/vehicle-server/http";
 import type { Logger } from "@danypops/vehicle-server/logging";
 import type { CreateArtifactInput } from "./artifact/artifact.ts";
@@ -577,6 +578,14 @@ export function createApp(deps: {
 	onOperationExecuted?: (operation: string, input: OperationInput) => void;
 	/** Defaults to a no-op (createVehicleHttpApp's own default) -- daemon.ts wires vehicleLogger() so a failed invocation is actually logged, not silently discarded. */
 	logger?: Logger;
+	/**
+	 * Backs GET /daemon/diagnose -- "who am I, and what happened recently" (see
+	 * @danypops/vehicle-server's daemon-lifecycle.ts), without a caller reading Papyrus's own
+	 * SQLite database or state files directly. Omitted (e.g. in most tests, which don't run a
+	 * real supervised daemon process) means the route 404s, matching how /health always exists
+	 * but this diagnostic identity does not until a real serveMain() supplies it.
+	 */
+	diagnose?: () => Promise<DaemonDiagnosis>;
 }): { fetch(request: Request): Promise<Response> } {
 	// Same Bearer token, daemon, and port as the rest of this API -- see ./handlers/registry.ts.
 	const vehicleApp = createVehicleHttpApp({ registry: deps.service.vehicle, token: deps.token, logger: deps.logger });
@@ -606,6 +615,10 @@ export function createApp(deps: {
 			if (request.method === "GET" && url.pathname === "/health") {
 				return json({ ok: true, version: VERSION, schema: deps.service.schemaState() });
 			}
+			if (request.method === "GET" && url.pathname === "/daemon/diagnose") {
+				if (!deps.diagnose) return json({ error: "daemon diagnose is unavailable on this instance" }, { status: 404 });
+				return json(await deps.diagnose());
+			}
 			if (request.method === "GET" && url.pathname === "/api/v1/ops") {
 				return json({ operations: deps.service.operationNames() });
 			}