@junghanacs/entwurf 0.39.0 → 0.41.0

package/pi-extensions/lib/remote-pair-transport.ts

@@ -0,0 +1,81 @@
+/**
+ * remote-pair-transport — the production process adapter behind #107's `RemoteTransport` (rail 2c).
+ *
+ * One child per send: `spawn(argv[0], argv.slice(1))` with no shell, stdin written once and closed,
+ * stdout and stderr captured separately. On the bound it signals ITS OWN child only (TERM, then KILL
+ * after a short grace); if the pipes are still held after one more grace, it closes its own read ends
+ * and settles as a timeout rather than waiting for a close that may never come. It is not a process manager: it tracks no
+ * other process, scans nothing, and never retries. Classification belongs to
+ * `classifyRemoteReceipt`; this module only reports what the child did.
+ */
+
+import { spawn } from "node:child_process";
+import type { RemoteTransport, RemoteTransportResult } from "./remote-pair-send.ts";
+
+const CAPTURE_CAP = 64 * 1024;
+const KILL_GRACE_MS = 2000;
+const FINAL_GRACE_MS = 2000;
+
+function capped(chunks: Buffer[], size: { n: number }, chunk: Buffer): void {
+	if (size.n >= CAPTURE_CAP) return;
+	const room = CAPTURE_CAP - size.n;
+	const piece = chunk.length > room ? chunk.subarray(0, room) : chunk;
+	chunks.push(piece);
+	size.n += piece.length;
+}
+
+export const processTransport: RemoteTransport = {
+	run(argv, stdin, timeoutMs): Promise<RemoteTransportResult> {
+		return new Promise((resolve) => {
+			const out: Buffer[] = [];
+			const err: Buffer[] = [];
+			const outN = { n: 0 };
+			const errN = { n: 0 };
+			let timedOut = false;
+			let spawnError: string | null = null;
+			let settled = false;
+			const child = spawn(argv[0], argv.slice(1), { shell: false, stdio: ["pipe", "pipe", "pipe"] });
+			let killTimer: NodeJS.Timeout | undefined;
+			let finalTimer: NodeJS.Timeout | undefined;
+			const settle = (code: number | null, signal: NodeJS.Signals | null): void => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(bound);
+				if (killTimer) clearTimeout(killTimer);
+				if (finalTimer) clearTimeout(finalTimer);
+				const stderr = Buffer.concat(err).toString("utf8");
+				resolve({
+					exitCode: spawnError ? null : code,
+					signal: spawnError ? null : signal,
+					timedOut,
+					stdout: Buffer.concat(out).toString("utf8"),
+					stderr: spawnError ? `spawn failed: ${spawnError}${stderr ? `\n${stderr}` : ""}` : stderr,
+				});
+			};
+			const bound = setTimeout(() => {
+				timedOut = true;
+				child.kill("SIGTERM");
+				killTimer = setTimeout(() => {
+					child.kill("SIGKILL");
+					// Something else may still hold our stdout/stderr pipes (an inherited descendant,
+					// an ssh ControlMaster). We do not chase it: after one more grace we close OUR read
+					// ends and settle as a timeout, which the receipt reads as indeterminate.
+					finalTimer = setTimeout(() => {
+						child.stdout.destroy();
+						child.stderr.destroy();
+						settle(child.exitCode, child.signalCode);
+					}, FINAL_GRACE_MS);
+				}, KILL_GRACE_MS);
+			}, timeoutMs);
+			child.stdout.on("data", (c: Buffer) => capped(out, outN, c));
+			child.stderr.on("data", (c: Buffer) => capped(err, errN, c));
+			child.on("error", (e) => {
+				spawnError = e.message;
+			});
+			// A child that exits before reading stdin closes the pipe; that is its outcome, not ours.
+			child.stdin.on("error", () => {});
+			child.on("close", (code, signal) => settle(code, signal));
+			child.stdin.end(stdin);
+		});
+	},
+};

package/pi-extensions/lib/resume-launch-identity.ts

@@ -1,29 +1,37 @@
 /**
- * resume-launch-identity — the RECORD-AUTHORITATIVE half of resuming a pi citizen,
- * kept after the visible-first cut removed everything that used to call it.
+ * resume-launch-identity — the RECORD-AUTHORITATIVE half of a visible same-id resume: garden id →
+ * the meta-record → which native session is this citizen's, and where it lives.
  *
- * It was the preamble of the `spawn-bg` watcher's `spawnChild` (entwurf-v2-spawn-production.ts,
- * deleted with that transport): garden id → the meta-record → the transcript that record
- * claims → the provider/model/cwd that transcript's own header carries. None of that is
- * about being hidden or visible. It is the answer to "which being is this, and which
- * conversation is theirs", and it is the same answer a VISIBLE resume will need.
+ * It began as the preamble of the retired `spawn-bg` watcher (garden id → the meta-record → the
+ * transcript that record claims → the provider/model/cwd that transcript's own header carries).
+ * None of that is about being hidden or visible; it is the answer to "which being is this, and
+ * which conversation is theirs". `entwurf-v2-visible-resume` is its consumer, and
+ * `check-resume-launch-identity` holds the record-integrity rules below — the transcript header id
+ * must equal `record.nativeSessionId`, an addressable read (#52) rather than a plain targeted one,
+ * a recorded ACP provider must resolve its bridge.
  *
- * So this leaf is preserved deliberately, with no consumer in the shipped tree today.
- * `check-resume-launch-identity` holds its contract so the record-integrity rules below —
- * the transcript header id must equal `record.nativeSessionId`, an addressable read
- * (#52) rather than a plain targeted one, a recorded ACP provider must resolve its
- * bridge — cannot rot while they wait.
+ * The domain is pi and claude-code (#147 L2). Both own their transcript and re-attach to the same
+ * record when their native session reopens; this leaf only names that session. For pi it reads
+ * the transcript header (the launch needs its provider/model/cwd). For claude-code it reads no
+ * transcript at all — the vendor owns it, and `claude --resume <id>` needs nothing from it — and
+ * checks only that the recorded path is an absolute file that still exists. Every other backend
+ * is a named refusal: native-push citizens have no resume authority (AGENTS Hard Rule 10), and a
+ * durable host is not reopened through Entwurf.
  *
  * It takes a bare garden id, not a plan: the plan type it used to destructure belonged to
  * the removed transport, and the identity question never needed the rest of it.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import path from "node:path";
 import { AcpModelNotCuratedError, isCuratedAcpModelId, PROVIDER_ID } from "./acp/model-ids.js";
 import { getEntwurfExplicitExtensions, readSessionIdentity } from "./entwurf-core.ts";
 import { readAddressableMetaIdentity } from "./meta-session.ts";
 
+/** The backends with a visible same-id resume. A closed set: nothing outside it is reopened. */
+export const RESUME_BACKENDS = ["pi", "claude-code"] as const;
+export type ResumeBackend = (typeof RESUME_BACKENDS)[number];
+
 /**
  * One of the TWO expected refusals on this leaf: the target is a citizen of a backend that has no
  * same-id resume at all. The other is `AcpModelNotCuratedError` (#128, `acp/model-ids.js`).
@@ -33,20 +41,22 @@ import { readAddressableMetaIdentity } from "./meta-session.ts";
  * bridge — and those keep their bare cause-rich `Error`, because a caller cannot act on them
  * except by looking. A Claude Code or agy garden id is different in kind: nothing is broken,
  * the operator simply asked a capability boundary to do something it does not cover, and the
- * honest answer is a named refusal rather than an error report about a store that is fine.
+ * honest answer is a named refusal rather than an error report about a store that is fine. Since
+ * #147 L2 the boundary is `RESUME_BACKENDS`; a Codex, agy, Copilot, OMP or pi-durable garden id is
+ * this refusal.
  *
  * It carries a `reason` so the caller matches on a FIELD. Parsing the message string would make
  * the wording load-bearing, and re-reading the record to ask "was it pi?" would read an address
  * twice and could answer differently the second time.
  */
 export class ResumeBackendUnsupportedError extends Error {
-	readonly reason = "target-not-pi" as const;
+	readonly reason = "target-backend-unsupported" as const;
 	readonly backend: string;
 	constructor(gardenId: string, backend: string) {
 		super(
 			`resume-launch-identity: ${gardenId} is a ${backend} citizen — same-id resume is a host-adapter relaunch ` +
-				`capability, and its domain currently contains backend pi only (only pi stands a control socket up). ` +
-				`This is a capability boundary, not the control-socket rail and not citizen rank.`,
+				`capability, and its domain is ${RESUME_BACKENDS.join(" and ")}. ` +
+				`This is a capability boundary, not citizen rank.`,
 		);
 		this.name = "ResumeBackendUnsupportedError";
 		this.backend = backend;
@@ -55,7 +65,8 @@ export class ResumeBackendUnsupportedError extends Error {
 
 /** The launch-time facts `buildResumePiArgs` needs, resolved from the meta-record + the
  * recorded transcript (record authority, #50 C2/C3). */
-export interface LaunchIdentity {
+export interface PiLaunchIdentity {
+	backend: "pi";
 	/** The EXACT session JSONL to resume — `pi --session <path>`. */
 	sessionFile: string;
 	cwd: string;
@@ -64,6 +75,79 @@ export interface LaunchIdentity {
 	model: string;
 }
 
+/**
+ * A Claude Code citizen's launch facts, all from the record. `nativeSessionId` is the argument of
+ * `claude --resume`; `createdAt` is carried so the observation can confirm the SAME record came
+ * back, not merely a record under the same garden id. `attachIncarnation` is the record's arm
+ * binding (#147 L2 B1), compared with the receiver marker's copy — `null` is carried as null,
+ * never filled. No model or permission flag is here: a resume does not restore the options a
+ * session was once started with.
+ */
+export interface ClaudeCodeLaunchIdentity {
+	backend: "claude-code";
+	nativeSessionId: string;
+	cwd: string;
+	createdAt: string;
+	attachIncarnation: string | null;
+}
+
+export type LaunchIdentity = PiLaunchIdentity | ClaudeCodeLaunchIdentity;
+
+/**
+ * Claude Code's session id grammar: a lowercase UUID. The value becomes an argv token after
+ * `--resume`, so anything else — a leading `-`, whitespace, a path — is refused as a bad record
+ * rather than handed to the vendor CLI as something it would parse differently.
+ */
+const CLAUDE_SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** A claude-code record → its resume facts. Throws, with its own cause, on a record that cannot be resumed. */
+function resolveClaudeCodeLaunchIdentity(
+	gardenId: string,
+	record: {
+		nativeSessionId: string;
+		cwd: string;
+		transcriptPath: string | null;
+		createdAt: string;
+		attachIncarnation: string | null;
+	},
+): ClaudeCodeLaunchIdentity {
+	if (!CLAUDE_SESSION_ID.test(record.nativeSessionId)) {
+		throw new Error(
+			`resume-launch-identity: ${gardenId} records nativeSessionId ${JSON.stringify(record.nativeSessionId)}, ` +
+				`which is not a Claude Code session id (lowercase UUID) — refusing to hand it to claude --resume.`,
+		);
+	}
+	const transcript = record.transcriptPath;
+	if (!transcript || !path.isAbsolute(transcript)) {
+		throw new Error(
+			`resume-launch-identity: ${gardenId} records no absolute transcriptPath (${JSON.stringify(transcript)}) — ` +
+				`the birth hook writes one for every Claude Code session, so this record cannot name a session to resume.`,
+		);
+	}
+	let isFile = false;
+	try {
+		isFile = statSync(transcript).isFile();
+	} catch {
+		isFile = false;
+	}
+	if (!isFile) {
+		throw new Error(
+			`resume-launch-identity: ${gardenId} recorded transcriptPath "${transcript}" is not a file on disk — ` +
+				`the session's transcript is gone, so claude --resume would open nothing.`,
+		);
+	}
+	if (!path.isAbsolute(record.cwd)) {
+		throw new Error(`resume-launch-identity: ${gardenId} records a relative cwd ${JSON.stringify(record.cwd)}.`);
+	}
+	return {
+		backend: "claude-code",
+		nativeSessionId: record.nativeSessionId,
+		cwd: record.cwd,
+		createdAt: record.createdAt,
+		attachIncarnation: record.attachIncarnation,
+	};
+}
+
 /**
  * Resolve launch identity for a resume. The TARGET is now resolved through the
  * meta-record (#50 C2): `gardenId → record.transcriptPath`. It used to be a global
@@ -95,6 +179,7 @@ export interface LaunchIdentity {
  */
 export function resolveResumeLaunchIdentity(gardenId: string): LaunchIdentity {
 	const record = readAddressableMetaIdentity(gardenId);
+	if (record.backend === "claude-code") return resolveClaudeCodeLaunchIdentity(gardenId, record);
 	if (record.backend !== "pi") {
 		throw new ResumeBackendUnsupportedError(gardenId, record.backend);
 	}
@@ -161,6 +246,7 @@ export function resolveResumeLaunchIdentity(gardenId: string): LaunchIdentity {
 	const model = explicitExtensions.modelOverride ?? resumeModel;
 	if (provider === PROVIDER_ID && !isCuratedAcpModelId(model)) throw new AcpModelNotCuratedError(model);
 	return {
+		backend: "pi",
 		sessionFile,
 		cwd: identity.cwd,
 		explicitExtensionArgs: explicitExtensions.args,

package/pi-extensions/lib/retirement-event.ts

@@ -0,0 +1,253 @@
+/**
+ * retirement-event — the #106 B machine-readable retirement record's APPEND leaf (#147).
+ *
+ * One target-gid-keyed append-only sidecar per citizen: `<retirementsDir>/<targetGardenId>.jsonl`,
+ * one closed v1 JSON line per event. The event body names both ends explicitly
+ * (`actorGardenId` / `targetGardenId`) — the filename is never the only carrier.
+ *
+ * What this leaf is NOT:
+ *   - not an identity field, liveness fact, dormancy proof, permission or grant. Nothing that
+ *     decides dispatch, facts, peers or resume reads it; there is no production reader at all.
+ *   - not a receipt framework. It appends exactly the event it is handed; minting `eventId`/`at`,
+ *     mapping a dispatch outcome to a summary and the requested/outcome ordering belong to the
+ *     caller's join.
+ *   - not a retention, GC or scanning surface. Absence of a line is `unknown`, never "no retire".
+ *
+ * Path: the directory is an explicit argument. The composition computes it ONCE from its own
+ * fixed sessions directory with `retirementsDirBesideSessions`; this module reads no environment
+ * and resolves no home directory.
+ *
+ * IO boundary (Linux-certified, same stance as `readStoreRecordFile` in meta-session.ts):
+ *   - the directory is created 0700 if absent (parent must exist); an existing entry must be a
+ *     real directory, never a symlink.
+ *   - the file is opened O_WRONLY|O_APPEND|O_CREAT|O_NOFOLLOW|O_NONBLOCK, 0600 on create. A final
+ *     symlink fails (ELOOP), a directory fails (EISDIR), a FIFO never blocks (ENXIO without a
+ *     reader; with one, the fstat check below refuses it).
+ *   - the OPENED fd must be a regular file with exactly one link (a hardlink is not appended to).
+ *   - the whole line is ONE writeSync; a short write is an error. A short write can leave a
+ *     partial tail line in the file — that is reported, never hidden or repaired here.
+ *   - fsyncSync, then close. fsync is a flush request to this file, not a power-loss or
+ *     multi-file transaction guarantee.
+ * Residual, outside this leaf: ancestors of the directory are not checked; an existing file's
+ * mode is not changed; a same-user process that can rename entries in the directory can swap the
+ * name after open (the write still lands on the inode that was checked). The threat model is the
+ * same-user store every other meta sidecar shares.
+ *
+ * Errors: an invalid event or a refused entry throws `RetirementEventError`; a native fs error
+ * (ELOOP, EISDIR, ENXIO, EIO, …) is thrown as it is. Either way the append fails ONCE — no retry.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isValidSessionId } from "./session-id.js";
+
+export const RETIREMENT_EVENT_VERSION = 1 as const;
+export const RETIREMENTS_DIR_NAME = "meta-retirements";
+export const RETIREMENT_EVENT_SUFFIX = ".jsonl";
+
+export type RetirementTargetBackend = "pi" | "claude-code";
+
+/**
+ * Which outcome statuses each backend can truthfully report: Pi's request boundaries
+ * (`shutdown-requested` is a request ACK, never an exit) and the Claude Code adapter's outcomes
+ * (`exited` is that fd-pinned process only). A cross-domain pair — Pi `exited`, Claude Code
+ * `shutdown-requested` — is refused, so it can never become a durable line. A dispatch-level
+ * unknown is `unknown` on either side.
+ */
+export const RETIREMENT_OUTCOME_STATUSES_BY_BACKEND = {
+	pi: ["shutdown-requested", "refused", "unknown"],
+	"claude-code": ["exited", "refused", "not-signalled", "unknown"],
+} as const satisfies Record<RetirementTargetBackend, readonly string[]>;
+export type RetirementOutcomeStatus = (typeof RETIREMENT_OUTCOME_STATUSES_BY_BACKEND)[RetirementTargetBackend][number];
+
+/**
+ * A closed semantic summary. `reason` is null or a short lowercase token; it is never detail,
+ * cause, stderr or other free text. The token check is a FORMAT check, not a secret sanitizer.
+ * The adapters' reason values are typed `string` (not an enum): which of them may be recorded,
+ * or mapped to null, is the composition's join to decide, not this leaf's.
+ */
+export interface RetirementOutcomeSummary {
+	status: RetirementOutcomeStatus;
+	reason: string | null;
+}
+
+export interface RetirementRequestedEvent {
+	v: typeof RETIREMENT_EVENT_VERSION;
+	kind: "retirement-requested";
+	eventId: string;
+	at: string;
+	actorGardenId: string;
+	targetGardenId: string;
+	targetBackend: RetirementTargetBackend;
+}
+
+export interface RetirementOutcomeEvent {
+	v: typeof RETIREMENT_EVENT_VERSION;
+	kind: "retirement-outcome";
+	eventId: string;
+	at: string;
+	actorGardenId: string;
+	targetGardenId: string;
+	targetBackend: RetirementTargetBackend;
+	outcome: RetirementOutcomeSummary;
+}
+
+export type RetirementEvent = RetirementRequestedEvent | RetirementOutcomeEvent;
+
+export class RetirementEventError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "RetirementEventError";
+	}
+}
+
+const EVENT_ID_RE = /^[0-9a-f]{32}$/;
+/** The shape of `Date#toISOString()` output; calendar validity is the round-trip below. */
+const AT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const REASON_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+const BASE_KEYS = ["v", "kind", "eventId", "at", "actorGardenId", "targetGardenId", "targetBackend"] as const;
+const OUTCOME_KEYS = ["status", "reason"] as const;
+
+/**
+ * Read a plain object's own DATA properties exactly once. A foreign prototype (and with it an
+ * inherited `toJSON`), an accessor or a symbol key refuses, so what is validated is what is
+ * written: serialization only ever sees the fresh object built from these values.
+ */
+function snapshotPlain(value: unknown, what: string): Map<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new RetirementEventError(`${what} must be an object`);
+	}
+	const proto = Object.getPrototypeOf(value);
+	if (proto !== Object.prototype && proto !== null) throw new RetirementEventError(`${what} must be a plain object`);
+	const descriptors = Object.getOwnPropertyDescriptors(value);
+	const fields = new Map<string, unknown>();
+	for (const key of Reflect.ownKeys(descriptors)) {
+		if (typeof key !== "string") throw new RetirementEventError(`${what} must not carry symbol keys`);
+		const descriptor = descriptors[key];
+		if (!("value" in descriptor)) throw new RetirementEventError(`${what}.${key} must be a data property`);
+		fields.set(key, descriptor.value);
+	}
+	return fields;
+}
+
+function requireExactKeys(fields: Map<string, unknown>, keys: readonly string[], what: string): void {
+	const extra = [...fields.keys()].filter((key) => !keys.includes(key));
+	const missing = keys.filter((key) => !fields.has(key));
+	if (extra.length > 0 || missing.length > 0) {
+		throw new RetirementEventError(
+			`${what} keyset is closed: missing [${missing.join(", ")}], not allowed [${extra.join(", ")}]`,
+		);
+	}
+}
+
+/** Exactly `Date#toISOString()` of a real instant: 2026-02-30 or 24:00 does not round-trip. */
+function isIsoInstant(value: unknown): value is string {
+	if (typeof value !== "string" || !AT_RE.test(value)) return false;
+	const ms = Date.parse(value);
+	return !Number.isNaN(ms) && new Date(ms).toISOString() === value;
+}
+
+/**
+ * Validate ONE snapshot of the event and return its exact on-disk bytes (canonical key order, one
+ * UTF-8 line) together with the target id taken from that same snapshot. The append routes the
+ * file by this id, never by re-reading the caller's object.
+ */
+function validateRetirementEvent(event: RetirementEvent): { bytes: Buffer; targetGardenId: string } {
+	const f = snapshotPlain(event, "retirement event");
+	const kind = f.get("kind");
+	if (kind !== "retirement-requested" && kind !== "retirement-outcome") {
+		throw new RetirementEventError(`unknown retirement event kind: ${String(kind)}`);
+	}
+	requireExactKeys(f, kind === "retirement-outcome" ? [...BASE_KEYS, "outcome"] : BASE_KEYS, `${kind} event`);
+	const v = f.get("v");
+	const eventId = f.get("eventId");
+	const at = f.get("at");
+	const actorGardenId = f.get("actorGardenId");
+	const targetGardenId = f.get("targetGardenId");
+	const targetBackend = f.get("targetBackend");
+	if (v !== RETIREMENT_EVENT_VERSION) throw new RetirementEventError(`unsupported event version: ${String(v)}`);
+	if (typeof eventId !== "string" || !EVENT_ID_RE.test(eventId)) {
+		throw new RetirementEventError("eventId must be 32 lowercase hex characters");
+	}
+	if (!isIsoInstant(at)) throw new RetirementEventError("at must be a valid Date#toISOString() instant");
+	if (!isValidSessionId(actorGardenId)) throw new RetirementEventError("actorGardenId is not a garden id");
+	if (!isValidSessionId(targetGardenId)) throw new RetirementEventError("targetGardenId is not a garden id");
+	if (targetBackend !== "pi" && targetBackend !== "claude-code") {
+		throw new RetirementEventError(`unsupported targetBackend: ${String(targetBackend)}`);
+	}
+	const base = { v, kind, eventId, at, actorGardenId, targetGardenId, targetBackend };
+	const line = (body: object) => ({ bytes: Buffer.from(`${JSON.stringify(body)}\n`, "utf8"), targetGardenId });
+	if (kind === "retirement-requested") return line(base);
+
+	const o = snapshotPlain(f.get("outcome"), "outcome summary");
+	requireExactKeys(o, OUTCOME_KEYS, "outcome summary");
+	const status = o.get("status");
+	const reason = o.get("reason");
+	const allowed: readonly unknown[] = RETIREMENT_OUTCOME_STATUSES_BY_BACKEND[targetBackend];
+	if (!allowed.includes(status)) {
+		throw new RetirementEventError(`outcome status ${String(status)} is not a ${targetBackend} outcome`);
+	}
+	if (reason !== null && (typeof reason !== "string" || !REASON_RE.test(reason))) {
+		throw new RetirementEventError("outcome reason must be null or a short lowercase token");
+	}
+	return line({ ...base, outcome: { status, reason } });
+}
+
+/** Validate one event and return its exact on-disk bytes: canonical key order, one UTF-8 line. */
+export function serializeRetirementEvent(event: RetirementEvent): Buffer {
+	return validateRetirementEvent(event).bytes;
+}
+
+/** Pure path: the sidecar directory beside a FIXED sessions directory. */
+export function retirementsDirBesideSessions(sessionsDir: string): string {
+	if (!path.isAbsolute(sessionsDir)) throw new RetirementEventError("sessionsDir must be an absolute path");
+	return path.join(path.dirname(path.resolve(sessionsDir)), RETIREMENTS_DIR_NAME);
+}
+
+export function retirementEventFile(retirementsDir: string, targetGardenId: string): string {
+	if (!path.isAbsolute(retirementsDir)) throw new RetirementEventError("retirementsDir must be an absolute path");
+	if (!isValidSessionId(targetGardenId)) throw new RetirementEventError("targetGardenId is not a garden id");
+	return path.join(retirementsDir, `${targetGardenId}${RETIREMENT_EVENT_SUFFIX}`);
+}
+
+function ensureRealDirectory(dir: string): void {
+	try {
+		fs.mkdirSync(dir, { mode: 0o700 });
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+	}
+	const st = fs.lstatSync(dir);
+	if (st.isSymbolicLink() || !st.isDirectory()) {
+		throw new RetirementEventError(`${path.basename(dir)} is not a real directory; refusing to append`);
+	}
+}
+
+/** Append ONE validated event line to the target's sidecar. Throws once on any failure. */
+export function appendRetirementEvent(retirementsDir: string, event: RetirementEvent): { bytes: number } {
+	const { bytes, targetGardenId } = validateRetirementEvent(event);
+	const file = retirementEventFile(retirementsDir, targetGardenId);
+	const { O_WRONLY, O_APPEND, O_CREAT, O_NOFOLLOW, O_NONBLOCK } = fs.constants;
+	if (!O_NOFOLLOW || !O_NONBLOCK) {
+		throw new RetirementEventError(
+			"this platform exposes no O_NOFOLLOW/O_NONBLOCK, so the append cannot refuse a symlink or FIFO",
+		);
+	}
+	ensureRealDirectory(retirementsDir);
+	const fd = fs.openSync(file, O_WRONLY | O_APPEND | O_CREAT | O_NOFOLLOW | O_NONBLOCK, 0o600);
+	try {
+		const st = fs.fstatSync(fd);
+		if (!st.isFile()) throw new RetirementEventError(`${path.basename(file)} is not a regular file`);
+		if (st.nlink !== 1) throw new RetirementEventError(`${path.basename(file)} has ${st.nlink} links; refusing`);
+		const written = fs.writeSync(fd, bytes, 0, bytes.length);
+		if (written !== bytes.length) {
+			throw new RetirementEventError(
+				`short write: ${written} of ${bytes.length} bytes; the file may now end in a partial line`,
+			);
+		}
+		fs.fsyncSync(fd);
+	} finally {
+		fs.closeSync(fd);
+	}
+	return { bytes: bytes.length };
+}