@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/session/agent-storage.ts

@@ -261,11 +261,46 @@ FROM model_usage_legacy
 					key: row.key,
 					error: String(error),
 				});
+				// A malformed row must fail the whole read: the migration drains
+				// rows only after a fully successful read, and deleting a row that
+				// never decoded would permanently lose its value. Throwing keeps
+				// every row (including the malformed one) in place for repair.
+				throw error;
 			}
 		}
 		return settings as Settings;
 	}
 
+	/**
+	 * @deprecated Settings are now stored in config.yml, not agent.db.
+	 * Clears the legacy settings rows after they have been drained into
+	 * config.yml so a later load never re-imports them (the database has no
+	 * other one-time guard). Retries transient SQLITE_BUSY contention with
+	 * exponential backoff and THROWS on persistent failure: the migration must
+	 * not treat a failed drain as success while stale rows stay eligible for
+	 * re-import on a later load.
+	 */
+	async clearSettings(): Promise<void> {
+		const maxRetries = 3;
+		const baseDelayMs = 100;
+		let lastError: Error | undefined;
+		for (let attempt = 0; attempt < maxRetries; attempt++) {
+			try {
+				this.#db.run("DELETE FROM settings");
+				return;
+			} catch (error) {
+				const isSqliteBusy =
+					error && typeof error === "object" && (error as { code?: string }).code === "SQLITE_BUSY";
+				if (!isSqliteBusy) {
+					throw error;
+				}
+				lastError = error as Error;
+				await Bun.sleep(baseDelayMs * 2 ** attempt);
+			}
+		}
+		throw lastError ?? new Error("Failed to clear legacy settings after retries");
+	}
+
 	/**
 	 * @deprecated Settings are now stored in config.yml, not agent.db.
 	 * This method is kept for backward compatibility but does nothing.

package/src/session/blob-store.ts

@@ -388,10 +388,41 @@ function removeResidentCacheTreeNoFollow(pathname: string): void {
 	fs.unlinkSync(pathname);
 }
 
+/**
+ * Disposal-time parent authority is an *identity* contract: the retained descriptor
+ * must still name the same owned directory, so a substituted parent (rename, symlink,
+ * or a foreign directory moved into place) fails closed and keeps disposal retryable.
+ *
+ * It deliberately does not re-assert the parent's owner-only mode. Adoption and every
+ * read/write path already refuse an untrusted (group/other-accessible) cache root, and
+ * the instance directory itself stays fully verified here — owner, mode, `O_NOFOLLOW`
+ * open, and post-rename `dev`/`ino` identity. Requiring owner-only mode on the parent
+ * *at disposal time* would instead turn a widened root into permanent retention of the
+ * predecessor's resident session bytes, which is the leak disposal exists to prevent.
+ */
+function assertResidentCacheDisposalParentIdentity(pathname: string, descriptor: number, uid: number): void {
+	let current: fs.Stats;
+	try {
+		current = fs.lstatSync(pathname);
+	} catch (error) {
+		throw residentCacheTrustError("directory_unverifiable", pathname, error);
+	}
+	if (!current.isDirectory() || current.isSymbolicLink() || current.uid !== uid)
+		throw new ResidentCacheTrustError("directory_untrusted", pathname);
+	let opened: fs.Stats;
+	try {
+		opened = fs.fstatSync(descriptor);
+	} catch (error) {
+		throw residentCacheTrustError("directory_descriptor_unverifiable", pathname, error);
+	}
+	if (!opened.isDirectory() || opened.uid !== uid || !hasSameFilesystemIdentity(current, opened))
+		throw new ResidentCacheTrustError("directory_identity_changed", pathname);
+}
+
 function assertResidentCacheDisposalParent(instanceDir: string, parentDescriptor: number): void {
 	const parentDir = path.dirname(instanceDir);
 	try {
-		assertResidentCacheDirectoryPathMatchesDescriptor(parentDir, parentDescriptor, residentCacheOwnerUid(parentDir));
+		assertResidentCacheDisposalParentIdentity(parentDir, parentDescriptor, residentCacheOwnerUid(parentDir));
 	} catch (error) {
 		throw residentCacheTrustError("parent_authority_changed", instanceDir, error);
 	}

package/src/session/coordinator-tool-label.ts

@@ -0,0 +1,40 @@
+import { UNPROVEN_TOOL_LABEL } from "../gjc-runtime/session-state-sidecar";
+import { TOOL_DESCRIPTORS } from "../tools/descriptors";
+
+/**
+ * Proves whether the tool OBJECT that actually ran is one this session constructed from a
+ * built-in descriptor, before any extension, MCP, or dynamically registered tool could
+ * override that registry name.
+ */
+export type BuiltinToolProvenance = (tool: object) => boolean;
+
+/**
+ * Canonical public label for the tool object a call was ACTUALLY dispatched to.
+ *
+ * The input is the object the producer bound to the event, never a name resolved here. A
+ * wire name is model text and the tool list behind it is mutable: a `setTools`, MCP
+ * reload, or tool refresh between dispatch and this call would otherwise publish whatever
+ * holds the name by now instead of what ran.
+ *
+ * Two independent facts must hold before a canonical label is published:
+ *
+ *  1. the producer bound a dispatched tool object at all (an unknown name the loop
+ *     rejected, and a call aborted before dispatch, bind nothing), AND
+ *  2. that object carries built-in provenance and its canonical name is one of the closed
+ *     built-in descriptors.
+ *
+ * The object check is what makes the label trustworthy. A registry name is not
+ * provenance: an SDK extension, MCP, or custom tool may register itself as `bash` or
+ * `edit`, or claim a built-in `customWireName`, and would otherwise be published under
+ * the built-in's label. Without proven provenance — including for a direct AgentSession
+ * construction that supplies none — the answer is `custom`.
+ */
+export function canonicalCoordinatorToolLabel(
+	dispatchedTool: object | undefined,
+	isBuiltinToolObject: BuiltinToolProvenance,
+): string {
+	if (!dispatchedTool || !isBuiltinToolObject(dispatchedTool)) return UNPROVEN_TOOL_LABEL;
+	const name = (dispatchedTool as { name?: unknown }).name;
+	if (typeof name !== "string" || !Object.hasOwn(TOOL_DESCRIPTORS, name)) return UNPROVEN_TOOL_LABEL;
+	return name;
+}

package/src/session/internal/managed-session-scope.ts

@@ -1090,6 +1090,10 @@ export function prepareManagedSessionScopeForWriteSync(
 				policy,
 			);
 		stage = "store";
+		// This must precede the first managed-store mutation: binding publication
+		// reconciles receipts with the normal 50k fail-closed bound, while an older
+		// macOS scope can contain only proven, terminal zero-byte remnants above it.
+		reapScrubbedProtocolRemnantsSync(scope.directoryPath);
 		let store: ManagedSessionDescendantStore;
 		const openManagedStore = (): ManagedSessionDescendantStore => {
 			const next = buildStore();

package/src/session/internal/managed-session-storage.ts

@@ -43,7 +43,7 @@ function nativeSessionStorage(): NativeManagedSessionStorage {
 
 export const MANAGED_ARTIFACT_MAX_DEPTH = 32;
 export const MANAGED_ARTIFACT_MAX_FILES = 50_000;
-export const MANAGED_ARTIFACT_MAX_FILE_BYTES = 64 * 1024 * 1024;
+export const MANAGED_ARTIFACT_MAX_FILE_BYTES = 128 * 1024 * 1024;
 export const MANAGED_ARTIFACT_MAX_TOTAL_BYTES = 512 * 1024 * 1024;
 const REPLACEMENT_CLEANUP_RECEIPT_MAX_BYTES = 64 * 1024;
 const REPLACEMENT_CLEANUP_RECEIPT_SCAN_LIMIT = MANAGED_ARTIFACT_MAX_FILES;
@@ -62,12 +62,14 @@ export class ManagedPublishError extends Error {
 		| "io_error"
 		| "durability_failed";
 	readonly diagnostic: string;
+	readonly stagingCleanupSafe: boolean;
 
 	constructor(classification: ManagedPublishError["classification"], outcome: NativePublishOutcome) {
 		super(classification);
 		this.name = "ManagedPublishError";
 		this.classification = classification;
 		this.diagnostic = formatNativePublishDiagnostic(outcome);
+		this.stagingCleanupSafe = mayCleanCurrentStaging(outcome);
 	}
 }
 export class ManagedReplaceError extends Error {
@@ -77,6 +79,9 @@ export class ManagedReplaceError extends Error {
 	readonly retainedSuccessorPath: string | undefined;
 	readonly retainedPlaceholderPath: string | undefined;
 	readonly retainedUnknownPath: string | undefined;
+	/** Path-free Windows NTSTATUS of the underlying pre-mutation failure, when
+	 * the native layer preserved one (e.g. `0xC0000043` for a sharing violation). */
+	readonly windowsErrorCode: string | undefined;
 	readonly replacementCause: unknown;
 
 	constructor(result: NativeExactUnlinkResult, cleanupReceiptPath: string, replacementCause?: unknown) {
@@ -89,6 +94,7 @@ export class ManagedReplaceError extends Error {
 		this.retainedSuccessorPath = result.retainedSuccessorPath;
 		this.retainedPlaceholderPath = result.retainedPlaceholderPath;
 		this.retainedUnknownPath = result.retainedUnknownPath;
+		this.windowsErrorCode = result.windowsErrorCode;
 		this.replacementCause = replacementCause;
 	}
 }
@@ -170,7 +176,7 @@ function sameDirectoryTreeSnapshotAfterRename(
 	);
 }
 
-class ManagedTreeMoveOutcomeError extends Error {
+export class ManagedTreeMoveOutcomeError extends Error {
 	constructor(
 		message: string,
 		readonly stagingCleanupSafe: boolean,
@@ -260,6 +266,17 @@ export interface ManagedAppendReceipt {
 	identity: ManagedFileIdentity;
 }
 
+function sameManagedIdentity(left: ManagedFileIdentity, right: ManagedFileIdentity): boolean {
+	return (
+		left.dev === right.dev &&
+		left.ino === right.ino &&
+		left.nlink === right.nlink &&
+		left.size === right.size &&
+		left.mtimeNs === right.mtimeNs &&
+		left.ctimeNs === right.ctimeNs
+	);
+}
+
 export interface ManagedBoundedAppendExpectation {
 	readonly dev: string;
 	readonly ino: string;
@@ -516,28 +533,30 @@ function reportScrubbedProtocolRemnantReap(reaped: number, failures: number): Sc
 		});
 	return { reaped, failures };
 }
+
 /**
  * Best-effort removal of scrubbed write-protocol remnants from one managed
  * directory. Only zero-length, single-link, non-symlink regular files whose
  * names carry a terminal remnant prefix and whose timestamps are older than
  * the age gate are removed: a zero-length single-link entry is exactly what
  * the scrub proof leaves behind, and non-zero entries (displaced predecessors
- * or detached receipts retained as evidence) are never touched. Failures are
- * swallowed — a concurrent same-owner writer may legitimately own or already
- * have reconciled any candidate.
+ * or detached receipts retained as evidence) are never touched. A proven
+ * concurrent disappearance (ENOENT) is benign; all other I/O failures are
+ * returned and logged once without aborting scope preparation.
  */
 export function reapScrubbedProtocolRemnantsSync(
 	directory: string,
 	minAgeMs: number = SCRUBBED_REMNANT_MIN_AGE_MS,
-): number {
+): ScrubbedProtocolRemnantReapResult {
 	let names: string[];
 	try {
 		names = fs.readdirSync(directory);
-	} catch {
-		return 0;
+	} catch (error) {
+		return reportScrubbedProtocolRemnantReap(0, isEnoent(error) ? 0 : 1);
 	}
 	const cutoff = Date.now() - minAgeMs;
 	let reaped = 0;
+	let failures = 0;
 	for (const name of names) {
 		if (!SCRUBBED_REMNANT_PREFIXES.some(prefix => name.startsWith(prefix))) continue;
 		const pathname = path.join(directory, name);
@@ -547,11 +566,11 @@ export function reapScrubbedProtocolRemnantsSync(
 			if (named.mtimeMs > cutoff) continue;
 			fs.unlinkSync(pathname);
 			reaped += 1;
-		} catch {
-			// Best effort: concurrently reconciled or removed remnants are not errors.
+		} catch (error) {
+			if (!isEnoent(error)) failures += 1;
 		}
 	}
-	return reaped;
+	return reportScrubbedProtocolRemnantReap(reaped, failures);
 }
 
 /** Number of candidate remnants inspected between event-loop yields. */
@@ -1336,25 +1355,32 @@ export class ManagedSessionDescendantStore {
 			fsyncDirectory(this.#baseDir);
 			return;
 		}
-		if (outcome.reason === "destination_exists") {
-			const existing = captureManagedFilePrefixNoFollow(destination, REPLACEMENT_CLEANUP_RECEIPT_MAX_BYTES);
-			if (existing.identity.sha256 !== pending.identity.sha256)
-				throw new Error("managed_replace_cleanup_receipt_invalid");
-			const removed = nativeSessionStorage().exactUnlink(receiptPath, {
-				dev: pending.identity.dev,
-				ino: pending.identity.ino,
-				nlink: pending.identity.nlink,
-				parentDev: this.#subtreeRoot.dev,
-				parentIno: this.#subtreeRoot.ino,
-				size: BigInt(pending.identity.size),
-				mtimeNs: pending.identity.mtimeNs,
-				sha256: pending.identity.sha256,
-				quarantineName: `.gjc-receipt-pending-remove-${pending.identity.dev.toString(16)}-${pending.identity.ino.toString(16)}`,
-			});
-			if (!exactUnlinkCompleted(removed) && removed.code !== "not_found")
-				throw new Error(`managed_replace_receipt_cleanup_pending:${removed.code ?? "unknown"}`);
-			fsyncDirectory(this.#baseDir);
-			return;
+		if (outcome.reason === "destination_exists" || outcome.reason === "invalid_request") {
+			const captureIfPresent = (pathname: string): ManagedFileSnapshot | undefined => {
+				try {
+					return captureManagedFilePrefixNoFollow(pathname, REPLACEMENT_CLEANUP_RECEIPT_MAX_BYTES);
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+					throw error;
+				}
+			};
+			const currentPending = captureIfPresent(receiptPath);
+			const existing = captureIfPresent(destination);
+			if (!currentPending && existing) {
+				if (
+					!sameReplacementIdentity(existing.identity, pending.identity) ||
+					existing.identity.sha256 !== pending.identity.sha256
+				)
+					throw new Error("managed_replace_cleanup_receipt_invalid");
+				fsyncDirectory(this.#baseDir);
+				return;
+			}
+			if (currentPending && !existing) throw publishFailure(outcome);
+			// Two names cannot both authoritatively represent the one receipt identity
+			// encoded in the canonical filename. A byte-identical copy has a different
+			// filesystem identity and would make the canonical receipt fail its next
+			// reconciliation, while a hard link violates the single-link capture fence.
+			throw new Error("managed_replace_cleanup_receipt_invalid");
 		}
 		throw publishFailure(outcome);
 	}
@@ -1473,6 +1499,72 @@ export class ManagedSessionDescendantStore {
 		this.#publishRetainedNoReplace(this.#relative(resolved), bytes);
 		this.#assertBound();
 	}
+	/**
+	 * Atomically publishes an already-written managed staging file without
+	 * materializing its contents. The staging file and destination must be
+	 * descendants of this retained store.
+	 */
+	publishStagedFileNoReplace(
+		sourceRelativePath: string,
+		destinationRelativePath: string,
+		expected: { bytes: number; sha256: string },
+	): void {
+		this.#beforeMutation();
+		this.#assertBound();
+		const source = this.#resolve(sourceRelativePath);
+		const destination = this.#resolve(destinationRelativePath);
+		const fd = fs.openSync(source, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+		let sourceIdentity: ManagedFileSnapshot["identity"] | undefined;
+		try {
+			const descriptorStat = fs.fstatSync(fd, { bigint: true });
+			const before = identity(descriptorStat);
+			const named = identity(fs.lstatSync(source, { bigint: true }));
+			if (
+				!descriptorStat.isFile() ||
+				before.nlink !== 1n ||
+				!sameIdentity(before, named) ||
+				before.size !== expected.bytes
+			)
+				throw new Error("managed_publish_identity_mismatch");
+			const digest = createHash("sha256");
+			const chunk = Buffer.allocUnsafe(1024 * 1024);
+			let offset = 0;
+			for (;;) {
+				const bytesRead = fs.readSync(fd, chunk, 0, chunk.length, offset);
+				if (bytesRead === 0) break;
+				digest.update(chunk.subarray(0, bytesRead));
+				offset += bytesRead;
+			}
+			if (digest.digest("hex") !== expected.sha256) throw new Error("managed_publish_identity_mismatch");
+			fs.fsyncSync(fd);
+			const after = identity(fs.fstatSync(fd, { bigint: true }));
+			const namedAfter = identity(fs.lstatSync(source, { bigint: true }));
+			if (!sameIdentity(before, after) || !sameIdentity(after, namedAfter))
+				throw new Error("managed_publish_identity_mismatch");
+			sourceIdentity = after;
+		} finally {
+			fs.closeSync(fd);
+		}
+		if (!sourceIdentity) throw new Error("managed_publish_identity_unavailable");
+		const relativeSource = this.#relative(source);
+		const relativeDestination = this.#relative(destination);
+		const published = this.#authority
+			? this.#authority.renameManagedFileNoReplace(
+					relativeSource,
+					relativeDestination,
+					sourceIdentity.dev.toString(),
+					sourceIdentity.ino.toString(),
+					sourceIdentity.size.toString(),
+					sourceIdentity.mtimeNs.toString(),
+					sourceIdentity.ctimeNs.toString(),
+					expected.sha256,
+				)
+			: nativeSessionStorage().renameNoReplacePath(source, destination);
+		const outcome = classifyNativePublishOutcome(published, this.#authority ? "retained_file" : "direct_rename");
+		if (!outcome.ok) throw publishFailure(outcome);
+		if (!this.#authority) fsyncDirectory(this.#baseDir);
+		this.#assertBound();
+	}
 
 	async replace(relativePath: string, bytes: Uint8Array): Promise<void> {
 		this.#beforeMutation();
@@ -1494,6 +1586,49 @@ export class ManagedSessionDescendantStore {
 		this.#assertBound();
 	}
 
+	replaceExpectedIdentitySync(relativePath: string, bytes: Uint8Array, expected: ManagedFileIdentity): void {
+		this.#beforeMutation();
+		this.#assertBound();
+		const resolved = this.#resolve(relativePath);
+		if (!this.#authority) {
+			const current = captureManagedFileIdentityStreamingNoFollow(resolved);
+			if (!sameManagedIdentity(current, expected)) throw new Error("managed_replace_identity_mismatch");
+			replaceManagedFileSync(resolved, bytes, this.#subtreeRoot, this.#policy, undefined, current);
+			this.#assertBound();
+			return;
+		}
+		const relative = this.#relative(resolved);
+		const observed = this.#authority.stat(relative);
+		if (!observed.ok || !observed.identity) {
+			const rawCode =
+				typeof (observed as { code?: unknown })?.code === "string" ? (observed as { code: string }).code : "";
+			// Authority reports "not_found" for missing, non-authority uses ENOENT.
+			// Normalize to ENOENT so callers' isEnoent() recovers via create.
+			const err = new Error(rawCode || "managed_replace_missing") as NodeJS.ErrnoException;
+			err.code = rawCode === "not_found" ? "ENOENT" : rawCode || "managed_replace_missing";
+			throw err;
+		}
+		const current = managedFileIdentityFromNative(observed.identity);
+		if (!sameManagedIdentity(current, expected)) throw new Error("managed_replace_identity_mismatch");
+		const expectedSha256 =
+			typeof observed.identity.sha256 === "string" && /^[0-9a-f]{64}$/i.test(observed.identity.sha256)
+				? observed.identity.sha256.toLowerCase()
+				: this.readExpected(relativePath)?.identity.sha256;
+		if (!expectedSha256) throw new Error("managed_replace_identity_unavailable");
+		const replaced = (this.#authority as RecoveryFsRoot & RetainedManagedReplacer).replaceManaged(
+			relative,
+			bytes,
+			observed.identity.dev,
+			observed.identity.ino,
+			observed.identity.size,
+			observed.identity.mtimeNs,
+			observed.identity.ctimeNs,
+			expectedSha256,
+		);
+		if (!replaced.ok) throw new Error(replaced.code ?? "managed_replace_failed");
+		this.#assertBound();
+	}
+
 	replaceExpected(relativePath: string, bytes: Uint8Array, expected: ManagedFileSnapshot): void {
 		this.#beforeMutation();
 		this.#assertBound();
@@ -1601,6 +1736,24 @@ export class ManagedSessionDescendantStore {
 		return managedAppendReceiptFromIdentity(managedFileIdentityFromNative(appended.identity));
 	}
 
+	appendExpectedIdentitySync(
+		relativePath: string,
+		bytes: Uint8Array,
+		expected: ManagedFileIdentity,
+	): ManagedAppendReceipt {
+		const bounded = this.captureBoundedAppendExpectation(relativePath);
+		if (
+			!bounded ||
+			bounded.dev !== expected.dev.toString() ||
+			bounded.ino !== expected.ino.toString() ||
+			bounded.size !== String(expected.size) ||
+			bounded.mtimeNs !== expected.mtimeNs.toString() ||
+			bounded.ctimeNs !== expected.ctimeNs.toString()
+		)
+			throw new Error("managed_append_identity_mismatch");
+		return this.appendExpectedSync(relativePath, bytes, bounded);
+	}
+
 	appendSync(relativePath: string, bytes: Uint8Array): ManagedAppendReceipt {
 		this.#beforeMutation();
 		this.#assertBound();
@@ -1608,7 +1761,13 @@ export class ManagedSessionDescendantStore {
 		if (this.#authority) {
 			const relative = this.#relative(resolved);
 			const observed = this.#authority.stat(relative);
-			if (!observed.ok || !observed.identity) throw new Error(observed.code ?? "managed_append_missing");
+			if (!observed.ok || !observed.identity) {
+				const rawCode =
+					typeof (observed as { code?: unknown })?.code === "string" ? (observed as { code: string }).code : "";
+				const err = new Error(rawCode || "managed_append_missing") as NodeJS.ErrnoException;
+				err.code = rawCode === "not_found" ? "ENOENT" : rawCode || "managed_append_missing";
+				throw err;
+			}
 			const nativeSha256 = observed.identity.sha256;
 			const expectedSha256 =
 				typeof nativeSha256 === "string" && /^[0-9a-f]{64}$/i.test(nativeSha256)
@@ -2884,6 +3043,15 @@ function replaceManagedFileGeneratedSync(
 				identity: publishedReceiptIdentity,
 				predecessor: expectedDestination,
 			};
+			// Transient Windows sharing violations (a concurrent holder denying delete
+			// sharing on the destination, issue #4330) are retried at the narrow
+			// pre-mutation syscall boundary inside the native `exactReplacePath`: the
+			// destination open is retried a bounded number of times while nothing has
+			// been renamed or unlinked, and only `sharing_violation`/`io_error` with no
+			// detached/retained paths can ever reach this throw from that open. This
+			// TypeScript layer deliberately never retries: once `exactReplacePath`
+			// returns, any failure that carries a detached/retained path is
+			// post-mutation evidence and must surface unchanged for receipt recovery.
 			const replaced = nativeSessionStorage().exactReplacePath(
 				staging,
 				destination,

package/src/session/messages.ts

@@ -122,7 +122,7 @@ export function readPendingDisplayTag(details: unknown): string | undefined {
  *  the CustomMessageEntry to disk. Scoped intentionally narrow: only fields
  *  declared here are stripped. Adding a new entry is a deliberate, reviewed
  *  change — unrelated future payload fields are never silently dropped. */
-export const INTERNAL_DETAILS_FIELDS = ["__pendingDisplayTag"] as const;
+export const INTERNAL_DETAILS_FIELDS = ["__pendingDisplayTag", "ownedCompletions"] as const;
 
 /** Return a `details` copy with every key in `INTERNAL_DETAILS_FIELDS`
  *  removed. Returns the input unchanged when there is nothing to strip

package/src/session/secure-token-file.ts

@@ -0,0 +1,80 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent } from "@gajae-code/utils";
+
+function isPosix(): boolean {
+	return process.platform !== "win32";
+}
+
+async function validateDirectory(directory: string): Promise<void> {
+	await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+	const stat = await fs.lstat(directory);
+	if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("Credential token directory is unsafe.");
+	if (isPosix()) {
+		if (typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+			throw new Error("Credential token directory has an unexpected owner.");
+		}
+		if ((stat.mode & 0o077) !== 0) await fs.chmod(directory, 0o700);
+		const repaired = await fs.lstat(directory);
+		if ((repaired.mode & 0o077) !== 0) throw new Error("Credential token directory is not owner-only.");
+	}
+}
+
+async function validateTokenPath(file: string): Promise<boolean> {
+	let stat: Awaited<ReturnType<typeof fs.lstat>>;
+	try {
+		stat = await fs.lstat(file);
+	} catch (error) {
+		if (isEnoent(error)) return false;
+		throw error;
+	}
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Credential token path is unsafe.");
+	if (isPosix()) {
+		if (typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+			throw new Error("Credential token file has an unexpected owner.");
+		}
+		if ((stat.mode & 0o077) !== 0) await fs.chmod(file, 0o600);
+		const repaired = await fs.lstat(file);
+		if ((repaired.mode & 0o077) !== 0) throw new Error("Credential token file is not owner-only.");
+	}
+	return true;
+}
+
+export async function readSecureTokenFile(file: string): Promise<string | null> {
+	await validateDirectory(path.dirname(file));
+	if (!(await validateTokenPath(file))) return null;
+	const handle = await fs.open(file, "r");
+	try {
+		const opened = await handle.stat();
+		if (!opened.isFile()) throw new Error("Credential token path is unsafe.");
+		const value = (await handle.readFile("utf8")).trim();
+		return value || null;
+	} finally {
+		await handle.close();
+	}
+}
+
+export async function writeSecureTokenFile(file: string, token: string): Promise<void> {
+	await validateDirectory(path.dirname(file));
+	if (await validateTokenPath(file)) {
+		await fs.writeFile(file, token, { mode: 0o600 });
+	} else {
+		await fs.writeFile(file, token, { flag: "wx", mode: 0o600 });
+	}
+	if (isPosix()) await fs.chmod(file, 0o600);
+}
+
+export async function createSecureTokenFileExclusive(file: string, token: string): Promise<boolean> {
+	await validateDirectory(path.dirname(file));
+	try {
+		await fs.writeFile(file, token, { flag: "wx", mode: 0o600 });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+			await validateTokenPath(file);
+			return false;
+		}
+		throw error;
+	}
+	if (isPosix()) await fs.chmod(file, 0o600);
+	return true;
+}