@junghanacs/entwurf 0.39.0 → 0.41.0

package/pi-extensions/lib/control-retire.ts

@@ -0,0 +1,195 @@
+/** Internal Pi lifecycle leaf, not an authorization boundary. The future core caller must
+ * authorize retirement (and reject self-retirement) before reaching this local socket.
+ * No prompt, abort, queue clearing, deferred shutdown, or retry is performed here.
+ */
+import type * as net from "node:net";
+import type { RpcResponse } from "./entwurf-control-rpc.js";
+
+export interface RetireContext {
+	readonly mode: string;
+	readonly sessionManager: { getSessionId(): string };
+	isIdle(): boolean;
+	hasPendingMessages(): boolean;
+	shutdown(): void;
+}
+
+/** Object identity is the session binding generation, captured when a connection is accepted.
+ * A listener may survive same-path rebinds; old accepted connections retain their old binding.
+ */
+export interface ControlBinding {
+	readonly gardenId: string;
+	readonly nativeSessionId: string;
+	readonly context: RetireContext;
+}
+
+export interface RetireState {
+	context: RetireContext | null;
+	binding: ControlBinding | null;
+	closing: boolean;
+	retireRequested: boolean;
+}
+
+export interface ControlServerState<C extends RetireContext> extends RetireState {
+	context: C | null;
+	server: net.Server | null;
+	socketPath: string | null;
+	connections: Set<net.Socket>;
+}
+
+/** Production start/rebind seam. Same-path rebind is entirely synchronous and performs NO
+ * listener/path IO. Each accept snapshots the binding via acceptControlConnection below.
+ */
+export async function startOrRebindControlServer<C extends RetireContext>(
+	state: ControlServerState<C>,
+	ctx: C,
+	socketPath: string,
+	gardenId: string,
+	io: {
+		prepare(): Promise<void>;
+		stop(): Promise<void>;
+		remove(socketPath: string): Promise<void>;
+		create(socketPath: string): Promise<net.Server>;
+	},
+): Promise<void> {
+	const binding: ControlBinding = { gardenId, nativeSessionId: ctx.sessionManager.getSessionId(), context: ctx };
+	const bind = () => {
+		state.context = ctx;
+		state.binding = binding;
+		state.closing = false;
+		state.retireRequested = false;
+	};
+	if (state.socketPath === socketPath && state.server) {
+		bind();
+		return;
+	}
+	await io.prepare();
+	await io.stop();
+	await io.remove(socketPath);
+	bind();
+	state.socketPath = socketPath;
+	state.server = await io.create(socketPath);
+}
+
+/** Snapshot exactly once, on accept, NOT when the listener was created or a command arrives. */
+export function acceptControlConnection(
+	state: Pick<ControlServerState<RetireContext>, "binding" | "connections">,
+	socket: net.Socket,
+): ControlBinding | null {
+	state.connections.add(socket);
+	socket.once("close", () => state.connections.delete(socket));
+	return state.binding;
+}
+
+export type RetireResult =
+	| { boundary: "shutdown-requested" }
+	| { boundary: "unknown"; reason: "shutdown-call-failed" }
+	| {
+			boundary: "refused";
+			reason:
+				| "target-closing"
+				| "target-stale"
+				| "target-context-unavailable"
+				| "target-non-tui"
+				| "target-busy"
+				| "target-pending";
+	  };
+
+/** Entire final check + SDK void call is synchronous. Call only AFTER any async preflight.
+ * A returned request receipt proves neither process exit nor persistence/flush completion.
+ * After requested/unknown, unobserved exit can leave a connect-alive socket refusing commands
+ * as target-closing until exit or a new session_start. No same-generation unlatch or retry.
+ */
+export function requestControlRetire(
+	state: RetireState,
+	serverBinding: ControlBinding | null,
+	residentGardenId: string | null,
+	expected: { gardenId: unknown; nativeSessionId: unknown },
+): RetireResult {
+	if (state.closing || state.retireRequested) return { boundary: "refused", reason: "target-closing" };
+	const ctx = state.context;
+	if (
+		!serverBinding ||
+		!ctx ||
+		state.binding !== serverBinding ||
+		ctx !== serverBinding.context ||
+		residentGardenId !== serverBinding.gardenId ||
+		expected.gardenId !== serverBinding.gardenId ||
+		expected.nativeSessionId !== serverBinding.nativeSessionId
+	) {
+		return { boundary: "refused", reason: "target-stale" };
+	}
+	let shutdown: () => void;
+	try {
+		if (ctx.sessionManager.getSessionId() !== serverBinding.nativeSessionId) {
+			return { boundary: "refused", reason: "target-stale" };
+		}
+		if (ctx.mode !== "tui") return { boundary: "refused", reason: "target-non-tui" };
+		if (!ctx.isIdle()) return { boundary: "refused", reason: "target-busy" };
+		if (ctx.hasPendingMessages()) return { boundary: "refused", reason: "target-pending" };
+		shutdown = ctx.shutdown;
+	} catch {
+		// SDK invalidates captured contexts on replacement/reload. Never call through one.
+		return { boundary: "refused", reason: "target-context-unavailable" };
+	}
+	state.retireRequested = true;
+	try {
+		shutdown.call(ctx);
+	} catch {
+		// The call may have started shutdown before throwing. Do not invite a replay.
+		return { boundary: "unknown", reason: "shutdown-call-failed" };
+	}
+	return { boundary: "shutdown-requested" };
+}
+
+/** Invalidate BEFORE waiting for server.close: accepted old connections must not act. */
+export function invalidateControlBinding(state: RetireState): void {
+	state.closing = true;
+	state.binding = null;
+	state.context = null;
+}
+
+/** The production receiver's one wire envelope. The RpcResponse import is type-only:
+ * no runtime dependency on the RPC client is introduced. An absent id is omitted by JSON;
+ * error is present only for refused/unknown, matching the strict core-side parser.
+ */
+export function retireResponseEnvelope(result: RetireResult, id?: string): RpcResponse {
+	return {
+		type: "response",
+		command: "retire",
+		id,
+		success: result.boundary === "shutdown-requested",
+		data: result,
+		...(result.boundary !== "shutdown-requested" ? { error: result.reason } : {}),
+	};
+}
+
+/** One response, then FIN; never wait for SDK termination to acknowledge its request.
+ * A failed transport leaves the caller with unknown outcome, not retry authority.
+ * The internal client sends one command per connection: concurrent responses on this same
+ * connection can be lost when retire sends FIN. It is not a multiplexed lifecycle protocol.
+ */
+export function endRetireResponse(socket: net.Socket, response: unknown): void {
+	try {
+		socket.end(`${JSON.stringify(response)}\n`);
+	} catch {
+		socket.destroy();
+	}
+}
+
+/** Session teardown only: flush accepted writes with FIN, then bound a non-cooperating peer.
+ * This timer exists solely for this server.close operation, not as a resident watcher.
+ * Applied to all session shutdowns: other in-flight replies may become transport-unknown.
+ */
+export async function closeControlConnections(server: net.Server, sockets: Set<net.Socket>): Promise<void> {
+	await new Promise<void>((resolve) => {
+		const timer = setTimeout(() => {
+			for (const socket of sockets) socket.destroy();
+		}, 250);
+		timer.unref();
+		server.close(() => {
+			clearTimeout(timer);
+			resolve();
+		});
+		for (const socket of sockets) socket.end();
+	});
+}

package/pi-extensions/lib/entwurf-control-rpc.ts

@@ -101,7 +101,23 @@ export interface RpcGetInfoCommand {
 	id?: string;
 }
 
-export type RpcCommand = RpcSendCommand | RpcGetMessageCommand | RpcClearCommand | RpcAbortCommand | RpcGetInfoCommand;
+/** Internal lifecycle request. The core must authorize it; this local socket is not
+ * a cryptographic authorization boundary. Exact target identity is mandatory.
+ */
+export interface RpcRetireCommand {
+	type: "retire";
+	gardenId: string;
+	nativeSessionId: string;
+	id?: string;
+}
+
+export type RpcCommand =
+	| RpcSendCommand
+	| RpcGetMessageCommand
+	| RpcClearCommand
+	| RpcAbortCommand
+	| RpcGetInfoCommand
+	| RpcRetireCommand;
 
 // ============================================================================
 // Accepted-connection disconnect policy (server half of the same wire)

package/pi-extensions/lib/entwurf-v2-retire-production.ts

@@ -0,0 +1,227 @@
+/**
+ * entwurf-v2-retire-production — the ctx-free PRODUCTION assembly of `retireCitizen`'s deps
+ * (#147). `makeProductionRetireDeps(opts)` binds the existing owning APIs — the v2 target lock,
+ * the meta-session readers, the control-socket inspection and probe, and the two internal
+ * retire adapters — into one `RetireDispatcherDeps`. Same shape as `makeProductionEntwurfV2Deps`:
+ * leaf IO seams are overridable for tests; which closure reaches which seam is not.
+ *
+ * Wiring, not a grant. Building or holding these deps confers no permission to retire anyone.
+ * `resolveCaller` is the trusted host's own caller resolution, injected at the wiring site (the
+ * bridge's private resolver, passed through unchanged); the dispatcher uses it for attribution
+ * and the self-target refusal only. No tool, index entry or annotation is registered here.
+ *
+ * ONE path set, from two sources. The lock and control-socket directories default to
+ * module-load constants (`ENTWURF_V2_LOCK_DIR`, `CONTROL_SOCKET_DIR`, HOME-derived when their
+ * modules load); this factory does not re-derive them. The sessions, receivers and senders
+ * directories default to an environment read made ONCE, at construction. Every closure uses
+ * that one set — including the Claude Code adapter's own record / receiver / sender witnesses,
+ * whose defaults would otherwise resolve their directories again on every call and could read
+ * a different store than the dispatcher. The capture covers these five directories (and the
+ * sidecar directory derived from the sessions one) only; the runtime environment below them
+ * (the CC helper's interpreter lookup, for one) is the adapter's own and is not frozen here.
+ * The CC helper path and spawn stay the adapter's defaults.
+ *
+ * `signal` is request-scoped: build these deps for ONE retire request. It is captured once and
+ * handed both to the dispatcher's own cancellation checks and, unchanged, to the CC adapter's
+ * abort checks; it is not an approval, and the Pi rail takes none.
+ *
+ * Recording: the #106 B sidecar directory is derived ONCE from the captured sessions directory
+ * (`retirementsDirBesideSessions`), never from a sixth path or environment knob. The two record
+ * callbacks are synchronous: each mints its event (random 128-bit id, ISO UTC `at`) and appends
+ * it once through the `append` seam; the requested callback returns the id only after its append
+ * returned. The outcome summary is a closed semantic code, never a cause, detail or stderr: Pi
+ * keeps its own closed reason code, a CC reason is always null (its status is kept; the full
+ * result stays on the wire receipt), an adapter throw is `unknown/adapter-threw` and a
+ * post-request cancellation `refused/request-aborted`. Nothing here mutates the identity store.
+ */
+
+import { randomBytes } from "node:crypto";
+import {
+	type CcRetireDeps,
+	type CcRetireExpected,
+	type CcRetireOptions,
+	type CcRetireResult,
+	makeCcRetireDeps,
+	requestCcRetire,
+} from "./cc-retire-request.ts";
+import type { SenderEnvelope } from "./entwurf-control-rpc.ts";
+import {
+	type AcquireLockResult,
+	ENTWURF_V2_LOCK_DIR,
+	type LockClaim,
+	type ReleaseResult,
+	acquireLock as realAcquireLock,
+	releaseLock as realReleaseLock,
+} from "./entwurf-v2-lock.ts";
+import type {
+	RetireDispatcherDeps,
+	RetireDispatchOutcome,
+	RetireRecordContext,
+	RetireTargetBackend,
+} from "./entwurf-v2-retire.ts";
+import { inspectReceiverMarker, type ReceiverInspection } from "./entwurf-v2-visible-resume.ts";
+import {
+	defaultMetaReceiversDir,
+	defaultMetaSendersDir,
+	defaultMetaSessionsDir,
+	type MetaIdentity,
+	type MetaSenderMarker,
+	metaRecordExistsByGardenId,
+	readAddressableMetaIdentity,
+	readMetaSenderMarker,
+} from "./meta-session.ts";
+import { type PiRetireRequestResult, requestPiRetire } from "./pi-retire-request.ts";
+import {
+	appendRetirementEvent,
+	RETIREMENT_EVENT_VERSION,
+	type RetirementEvent,
+	type RetirementOutcomeSummary,
+	retirementsDirBesideSessions,
+} from "./retirement-event.ts";
+import { CONTROL_SOCKET_DIR, inspectControlSocketPath, type TargetSocketInspection } from "./socket-discovery.ts";
+import { probeSocketLiveness, type SocketLiveness } from "./socket-probe.ts";
+
+/** The leaf IO the factory calls. Each defaults to the real owning function; tests override
+ * them with spies to prove which directory reaches which seam. */
+export interface ProductionRetireSeams {
+	acquireLock: (gid: string, deps: { dir: string }) => AcquireLockResult;
+	releaseLock: (claim: LockClaim, deps: { dir: string }) => ReleaseResult;
+	metaRecordExists: (gid: string, sessionsDir: string) => boolean;
+	readIdentity: (gid: string, sessionsDir: string) => MetaIdentity;
+	inspectPath: (socketPath: string) => Promise<TargetSocketInspection>;
+	probeSocket: (socketPath: string) => Promise<SocketLiveness>;
+	inspectReceiver: (gid: string, receiversDir: string) => ReceiverInspection;
+	readSender: (opts: { backend: "claude-code"; ownerPid: number; sendersDir: string }) => MetaSenderMarker | null;
+	requestPi: (
+		target: MetaIdentity,
+		expected: { gardenId: string; nativeSessionId: string },
+		options: { controlSocketDir: string },
+	) => Promise<PiRetireRequestResult>;
+	requestCc: (expected: CcRetireExpected, deps: CcRetireDeps, options: CcRetireOptions) => Promise<CcRetireResult>;
+	append: (retirementsDir: string, event: RetirementEvent) => { bytes: number };
+}
+
+type PiReason = Extract<PiRetireRequestResult, { reason: string }>["reason"];
+/** Pi's closed reason union, exhaustively (a Record keyed by it fails to type if one is added or
+ * removed). Only these codes reach the sidecar; anything else becomes null. */
+const PI_REASON_CODES: Record<PiReason, true> = {
+	"target-backend-unsupported": true,
+	"target-identity-mismatch": true,
+	"target-closing": true,
+	"target-stale": true,
+	"target-context-unavailable": true,
+	"target-non-tui": true,
+	"target-busy": true,
+	"target-pending": true,
+	"malformed-response": true,
+	"transport-error": true,
+	"shutdown-call-failed": true,
+};
+
+/** The closed summary of an attempt that was recorded as requested. Any other outcome kind is a
+ * composition fault and throws, which the dispatcher reports as an outcome-record failure. */
+function summarizeAttempt(backend: RetireTargetBackend, outcome: RetireDispatchOutcome): RetirementOutcomeSummary {
+	if (outcome.kind === "pi" && backend === "pi") {
+		const { result } = outcome;
+		const reason = "reason" in result && Object.hasOwn(PI_REASON_CODES, result.reason) ? result.reason : null;
+		return { status: result.boundary, reason };
+	}
+	if (outcome.kind === "claude-code" && backend === "claude-code")
+		return { status: outcome.result.outcome, reason: null };
+	if (outcome.kind === "unknown" && outcome.backend === backend) return { status: "unknown", reason: "adapter-threw" };
+	if (outcome.kind === "refused" && outcome.reason === "request-aborted") {
+		return { status: "refused", reason: "request-aborted" };
+	}
+	throw new Error(`no retirement summary for a ${outcome.kind} outcome on ${backend}`);
+}
+
+export interface ProductionRetireOpts {
+	/** The trusted host's caller resolution (attribution / self-target refusal), NOT authorization. */
+	resolveCaller: () => Promise<SenderEnvelope | null>;
+	/** This request's abort signal, for the core cancellation checks and the CC adapter. */
+	signal?: AbortSignal;
+	lockDir?: string;
+	sessionsDir?: string;
+	receiversDir?: string;
+	sendersDir?: string;
+	controlSocketDir?: string;
+	/** Test seam overrides — defaults are the real IO. */
+	seams?: Partial<ProductionRetireSeams>;
+}
+
+export function makeProductionRetireDeps(opts: ProductionRetireOpts): RetireDispatcherDeps {
+	// ── ONE path set: two module-load constants, three construction-time reads ──
+	const lockDir = opts.lockDir ?? ENTWURF_V2_LOCK_DIR;
+	const sessionsDir = opts.sessionsDir ?? defaultMetaSessionsDir();
+	const receiversDir = opts.receiversDir ?? defaultMetaReceiversDir();
+	const sendersDir = opts.sendersDir ?? defaultMetaSendersDir();
+	const controlSocketDir = opts.controlSocketDir ?? CONTROL_SOCKET_DIR;
+	const retirementsDir = retirementsDirBesideSessions(sessionsDir);
+	const signal = opts.signal;
+
+	const s = opts.seams ?? {};
+	const io: ProductionRetireSeams = {
+		acquireLock: s.acquireLock ?? realAcquireLock,
+		releaseLock: s.releaseLock ?? realReleaseLock,
+		metaRecordExists: s.metaRecordExists ?? metaRecordExistsByGardenId,
+		readIdentity: s.readIdentity ?? readAddressableMetaIdentity,
+		inspectPath: s.inspectPath ?? ((socketPath) => inspectControlSocketPath(socketPath)),
+		probeSocket: s.probeSocket ?? probeSocketLiveness,
+		inspectReceiver: s.inspectReceiver ?? inspectReceiverMarker,
+		readSender: s.readSender ?? readMetaSenderMarker,
+		requestPi: s.requestPi ?? requestPiRetire,
+		requestCc: s.requestCc ?? ((expected, deps, options) => requestCcRetire(expected, deps, options)),
+		append: s.append ?? appendRetirementEvent,
+	};
+	const attribution = (context: RetireRecordContext) => ({
+		actorGardenId: context.actorGardenId,
+		targetGardenId: context.targetGardenId,
+		targetBackend: context.targetBackend,
+	});
+
+	// The CC adapter's three witnesses, closed over the SAME directories as the dispatcher's own
+	// reads. Its helper path and spawn are left to the adapter's defaults.
+	const ccDeps = makeCcRetireDeps({
+		readRecord: (gid) => io.readIdentity(gid, sessionsDir),
+		inspectReceiver: (gid) => io.inspectReceiver(gid, receiversDir),
+		readSender: (ownerPid) => io.readSender({ backend: "claude-code", ownerPid, sendersDir }),
+	});
+
+	return {
+		resolveCaller: opts.resolveCaller,
+		// ONE lock domain: acquire and release are bound to the same directory.
+		acquireLock: (gid) => io.acquireLock(gid, { dir: lockDir }),
+		releaseLock: (claim) => io.releaseLock(claim, { dir: lockDir }),
+		recordExists: (gid) => io.metaRecordExists(gid, sessionsDir),
+		readIdentity: (gid) => io.readIdentity(gid, sessionsDir),
+		controlSocketDir,
+		inspectPath: (socketPath) => io.inspectPath(socketPath),
+		probeSocket: (socketPath) => io.probeSocket(socketPath),
+		requestPi: (target, expected, options) =>
+			io.requestPi(target, expected, { controlSocketDir: options.controlSocketDir }),
+		requestCc: (expected) => io.requestCc(expected, ccDeps, { signal }),
+		recordRequested: (context) => {
+			const eventId = randomBytes(16).toString("hex");
+			io.append(retirementsDir, {
+				v: RETIREMENT_EVENT_VERSION,
+				kind: "retirement-requested",
+				eventId,
+				at: new Date().toISOString(),
+				...attribution(context),
+			});
+			return eventId;
+		},
+		recordOutcome: (eventId, context, outcome) => {
+			io.append(retirementsDir, {
+				v: RETIREMENT_EVENT_VERSION,
+				kind: "retirement-outcome",
+				eventId,
+				at: new Date().toISOString(),
+				...attribution(context),
+				outcome: summarizeAttempt(context.targetBackend, outcome),
+			});
+			return undefined;
+		},
+		signal,
+	};
+}