@akagilnc/pi-workflow-roles 0.1.5365 → 0.1.5375

package/src/collector-config.ts

@@ -1,6 +1,8 @@
-import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 
+import { sha256Hex } from "./sha256.ts";
+import { isRecord } from "./unknown-value.ts";
+
 export const COLLECTOR_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
 export const COLLECTOR_REPO_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,98}[A-Za-z0-9])?$/;
 
@@ -51,17 +53,13 @@ export function parseCollectorPrNumber(raw: unknown): number {
   return value;
 }
 
-function record(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function canonicalManifest(requests: readonly CollectorRequestConfig[]): string {
   return `${JSON.stringify({ requests: requests.map((request) => ({ id: request.id, body: request.requestBody })) })}\n`;
 }
 
 export function emptyCollectorManifest(): CollectorManifest {
   const canonicalJson = canonicalManifest([]);
-  return { requests: [], canonicalJson, digest: createHash("sha256").update(canonicalJson).digest("hex") };
+  return { requests: [], canonicalJson, digest: sha256Hex(canonicalJson) };
 }
 
 /** Optional request configuration. It names requests, never expected observers. */
@@ -70,17 +68,17 @@ export async function loadCollectorManifest(path: string): Promise<CollectorMani
   try { bytes = await readFile(path); } catch (error) { fail(`Collector request manifest is unreadable at ${path}`, error); }
   let parsed: unknown;
   try { parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)); } catch (error) { fail("Collector request manifest must be UTF-8 JSON", error); }
-  if (!record(parsed)) fail("Collector request manifest must be an object");
+  if (!isRecord(parsed)) fail("Collector request manifest must be an object");
   const rawRequests = parsed.requests ?? [];
   if (!Array.isArray(rawRequests)) fail("Collector request manifest requests must be an array");
   const requests: CollectorRequestConfig[] = [];
   const ids = new Set<string>();
   for (const [index, item] of rawRequests.entries()) {
-    if (!record(item) || typeof item.id !== "string" || item.id.length === 0 || typeof item.body !== "string" || item.body.trim() === "") fail(`Collector request manifest requests[${index}] is invalid`);
+    if (!isRecord(item) || typeof item.id !== "string" || item.id.length === 0 || typeof item.body !== "string" || item.body.trim() === "") fail(`Collector request manifest requests[${index}] is invalid`);
     if (ids.has(item.id)) fail(`Collector request manifest has duplicate request id "${item.id}"`);
     ids.add(item.id);
     requests.push({ id: item.id, requestBody: item.body });
   }
   const canonicalJson = canonicalManifest(requests);
-  return { requests, canonicalJson, digest: createHash("sha256").update(canonicalJson).digest("hex"), sourcePath: path };
+  return { requests, canonicalJson, digest: sha256Hex(canonicalJson), sourcePath: path };
 }

package/src/compliance-transport.ts

@@ -8,6 +8,7 @@ import { officerConclusionReask } from "./gatekeeper-role.ts";
 import { receivedDiscriminator } from "./submission-errors.ts";
 import { coalesceSubmissionRows } from "./public-cli/terminal.ts";
 import { readableGateItem } from "./readable-gate-item.ts";
+import { isRecord } from "./unknown-value.ts";
 
 export type ComplianceNoReceipt = NoReceiptLifecycleFacts & { status: "no-receipt"; usage?: Usage };
 /**
@@ -63,7 +64,7 @@ function readListField(value: unknown): readonly unknown[] { return Array.isArra
 
 /** Try to project a known three-state compliance decision; undefined when not converged/continue/escalate. */
 export function tryReadComplianceCandidate(arguments_: unknown, usage?: Usage): ComplianceDecision | undefined {
-  if (typeof arguments_ !== "object" || arguments_ === null || Array.isArray(arguments_)) {
+  if (!isRecord(arguments_)) {
     return undefined;
   }
   const args = arguments_ as Record<string, unknown>;

package/src/countersign-contracts.ts

@@ -6,6 +6,7 @@
  */
 
 import { REVIEW_QUEUE_STATUSES, REVIEW_SUBMISSION_OUTPUT_TOOL_NAME } from "./review-submission.ts";
+import { isRecord } from "./unknown-value.ts";
 
 export const COUNTERSIGN_OUTPUT_TOOL_NAME = REVIEW_SUBMISSION_OUTPUT_TOOL_NAME;
 
@@ -25,7 +26,7 @@ export type CountersignVerdict =
   };
 
 export function validateRecordedCountersignOutput(verdict: unknown): CountersignVerdict {
-  if (verdict === null || typeof verdict !== "object" || Array.isArray(verdict)) {
+  if (!isRecord(verdict)) {
     throw new Error("Countersign verdict has no execution discriminator");
   }
   let status: unknown;

package/src/diarist-contracts.ts

@@ -12,6 +12,7 @@ import {
   type TicketProvenanceSession,
 } from "./ticket-provenance-contracts.ts";
 import { isSafePositiveTicketNumber } from "./run-ticket-number.ts";
+import { isRecord } from "./unknown-value.ts";
 
 export const DIARIST_OUTPUT_TOOL_NAME = "ak_diarist_output";
 
@@ -43,7 +44,7 @@ export type DiaristOutput =
     };
 
 export function validateRecordedDiaristOutput(value: unknown): DiaristOutput {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+  if (!isRecord(value)) {
     throw new Error("Diarist output has no execution discriminator");
   }
   let status: unknown;
@@ -78,7 +79,7 @@ export function projectDiaristTicketSessions(
   if (!Array.isArray(raw)) return undefined;
   const perTicket = new Map<number, TicketProvenanceSession[]>();
   for (const entry of raw) {
-    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return undefined;
+    if (!isRecord(entry)) return undefined;
     const { ticketNumber, sessions: rawSessions } = entry as Record<string, unknown>;
     if (!isSafePositiveTicketNumber(ticketNumber)) return undefined;
     const sessions = projectTicketProvenanceSessions(rawSessions);

package/src/doctor-contracts.ts

@@ -3,6 +3,8 @@ import { canonicalJson } from "./canonical-json.ts";
 import { openToolObject } from "./open-tool-schema.ts";
 import { withTerminatingOutputDeclarations } from "./package-contracts/terminating-infrastructure.ts";
 
+import { isRecord } from "./unknown-value.ts";
+
 export const DOCTOR_EVIDENCE_TOOL_NAME = "ak_doctor_evidence";
 export const DOCTOR_OUTPUT_TOOL_NAME = "ak_doctor_output";
 export const DOCTOR_AUDIT_TOOL_NAME = "ak_doctor_audit_decision";
@@ -85,7 +87,7 @@ export const doctorSubmissionSchema = withTerminatingOutputDeclarations(
 // consumes extra fields, so a closed object only rejects the role for saying more.
 export const doctorEvidenceReadSchema = Type.Object({ evidenceId: Type.String({ minLength: 1, description: "待读留存证据标识" }), offset: Type.Optional(Type.Integer({ minimum: 0, description: "起始字节偏移（从 0 计）" })), limit: Type.Optional(Type.Integer({ minimum: 1, description: "返回字节数（无上限）" })) }, { additionalProperties: true });
 export class DoctorSubmissionContractError extends Error { override readonly name = "DoctorSubmissionContractError"; }
-function isRecord(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+
 function read(value: unknown, key: string): unknown { if (!isRecord(value)) return undefined; try { return value[key]; } catch { return undefined; } }
 export function validateDoctorSubmissionShape(value: unknown): DoctorSubmission {
   return value as DoctorSubmission;

package/src/doctor-evidence.ts

@@ -4,26 +4,27 @@ import { sha256Hex } from "./sha256.ts";
 import type { DoctorCase, DoctorCaseCost, DoctorCount, DoctorEvidenceEntry } from "./doctor-contracts.ts";
 import { AcceptedDetailsContractError, acceptedFacts, isTerminatingToolName, validateAcceptedDetails } from "./package-contracts/terminating-tools.ts";
 
-function record(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+import { isRecord, isMissingPathError } from "./unknown-value.ts";
+
 async function discoverCaseFiles(root: string): Promise<string[]> { const found: string[] = []; async function walk(dir: string, depth: number) { for (const item of await readdir(dir, { withFileTypes: true })) { const path = resolve(dir, item.name); if (item.isDirectory()) { await walk(path, depth + 1); } else if (item.isFile() && (item.name.endsWith(".jsonl") || (item.name === "stderr.log" && depth === 1))) found.push(path); } } await walk(root, 0); return found.sort(); }
 function sourceList(count: number, sources: string[]) { return { count, sources: [...new Set(sources)].sort() }; }
 function accumulate(metric: DoctorCount, value: number, source: string) { metric.count += value; if (value) metric.sources.push(source); }
 function timestamp(row: Record<string, unknown>) { return typeof row.timestamp === "string" && Number.isFinite(Date.parse(row.timestamp)) ? row.timestamp : undefined; }
-function isMissingPathError(error: unknown): boolean { return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR"); }
+
 async function stableRunsIdentity(root: string): Promise<string> { let cursor = root; while (true) { try { const git = await stat(resolve(cursor, ".git")); if (git.isDirectory() || git.isFile()) return relative(cursor, root).split(sep).join("/"); } catch (error) { if (!isMissingPathError(error)) throw error; } const parent = dirname(cursor); if (parent === cursor) return root; cursor = parent; } }
 
 type SessionDerivation = { session: DoctorCaseCost["sessions"][number]; turns: number; calls: number; tokens: number; statuses: DoctorCaseCost["statuses"]; commits: DoctorCaseCost["commits"] };
 function deriveSession(content: string, id: string): SessionDerivation {
   const rows: Record<string, unknown>[] = []; const degradationReasons: string[] = [];
-  for (const line of content.split("\n")) if (line.trim()) { try { const row: unknown = JSON.parse(line); if (!record(row)) { degradationReasons.push(`non-object session row in ${id}`); break; } rows.push(row); } catch (error) { if (error instanceof SyntaxError) { degradationReasons.push(`malformed JSON tail in ${id}: ${error.message}`); break; } throw error; } }
+  for (const line of content.split("\n")) if (line.trim()) { try { const row: unknown = JSON.parse(line); if (!isRecord(row)) { degradationReasons.push(`non-object session row in ${id}`); break; } rows.push(row); } catch (error) { if (error instanceof SyntaxError) { degradationReasons.push(`malformed JSON tail in ${id}: ${error.message}`); break; } throw error; } }
   const started = rows.find((row) => row.type === "session"); const startedAt = started && timestamp(started); if (!startedAt) degradationReasons.push(`Pi session header is missing: ${id}`);
   let accepted: Record<string, unknown> | undefined, observedCommit: string | undefined, turns = 0, calls = 0, tokens = 0;
   const statuses: DoctorCaseCost["statuses"] = [], commits: DoctorCaseCost["commits"] = [];
   for (const row of rows) {
-    if (row.type === "custom" && row.customType === "ak-role-submission-closure" && record(row.data) && row.data.isError === false && typeof row.data.toolName === "string" && isTerminatingToolName(row.data.toolName)) accepted = row;
-    const message = record(row.message) ? row.message : undefined;
-    if (message?.role === "assistant") { for (const part of Array.isArray(message.content) ? message.content : []) if (record(part) && part.type === "toolCall") calls++; if (typeof message.responseId === "string") { turns++; const usage = record(message.usage) ? message.usage : undefined; if (usage && typeof usage.output === "number") tokens += usage.output; } }
-    if (message?.role === "toolResult" && message.isError !== true && typeof message.toolName === "string" && isTerminatingToolName(message.toolName) && record(message.details)) { let details; try { details = validateAcceptedDetails(message.toolName, message.details); } catch (error) { // Contract: README.md#Doctor — non-accepted terminating receipts are expected-negative evidence and are skipped; all other validation failures propagate with their cause.
+    if (row.type === "custom" && row.customType === "ak-role-submission-closure" && isRecord(row.data) && row.data.isError === false && typeof row.data.toolName === "string" && isTerminatingToolName(row.data.toolName)) accepted = row;
+    const message = isRecord(row.message) ? row.message : undefined;
+    if (message?.role === "assistant") { for (const part of Array.isArray(message.content) ? message.content : []) if (isRecord(part) && part.type === "toolCall") calls++; if (typeof message.responseId === "string") { turns++; const usage = isRecord(message.usage) ? message.usage : undefined; if (usage && typeof usage.output === "number") tokens += usage.output; } }
+    if (message?.role === "toolResult" && message.isError !== true && typeof message.toolName === "string" && isTerminatingToolName(message.toolName) && isRecord(message.details)) { let details; try { details = validateAcceptedDetails(message.toolName, message.details); } catch (error) { // Contract: README.md#Doctor — non-accepted terminating receipts are expected-negative evidence and are skipped; all other validation failures propagate with their cause.
         if (error instanceof AcceptedDetailsContractError) continue; throw error; } const facts = acceptedFacts(message.toolName, details); if (facts.commit && facts.commit !== observedCommit) { commits.push({ source: id, commit: facts.commit }); observedCommit = facts.commit; } /* #836 B10.3: do not wipe earlier statuses or invent a code status sentence */ if (facts.status !== undefined) { statuses.push({ source: id, status: facts.status }); } }
   }
   const acceptedAt = accepted && timestamp(accepted); const final = acceptedAt ? accepted! : rows.at(-1); const endedAt = final && timestamp(final); const wall = startedAt && endedAt ? Date.parse(endedAt) - Date.parse(startedAt) : undefined;

package/src/doctor-role.ts

@@ -5,6 +5,8 @@ import { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_DESCRIPTION, DOCTOR_OUTPU
 
 import { sitianReport } from "./sitian-facade.ts";
 
+import { errorText } from "./unknown-value.ts";
+
 export { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME };
 export const DOCTOR_CASE_FLAG = { name: "ak-doctor-case", definition: { description: "Retained .ak-roles/books/<book>/<n>/runs directory", type: "string" as const } } as const;
 export type DoctorRoleDependencies = { loadSoul(): Promise<string>; loadCase(path: string): Promise<DoctorCase> };
@@ -19,14 +21,14 @@ function appendCandidate(ctx: HostContext, data: unknown): void {
       source: "doctor-role",
     });
   } catch (error) {
-    throw new ComplianceResponseRetentionError(`太医署候选留存失败: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    throw new ComplianceResponseRetentionError(`太医署候选留存失败: ${errorText(error)}`, { cause: error });
   }
   const append = ctx.sessionManager.appendCustomEntry;
   if (typeof append === "function") {
     try {
       append.call(ctx.sessionManager, DOCTOR_CANDIDATE_ENTRY_TYPE, data);
     } catch (error) {
-      throw new ComplianceResponseRetentionError(`太医署候选留存失败: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+      throw new ComplianceResponseRetentionError(`太医署候选留存失败: ${errorText(error)}`, { cause: error });
     }
   }
 }

package/src/dossier-resolution.ts

@@ -9,6 +9,8 @@ import { resolve } from "node:path";
 
 import { runDirectoryFromHostContext, type HostContext } from "./host-contracts.ts";
 
+import { isRecord } from "./unknown-value.ts";
+
 export const AUDIT_RUN_DIR_ENV = "AK_ROLE_RUN_DIR" as const;
 export const DOCTOR_CANDIDATE_ENTRY_TYPE = "ak_doctor_audit_candidate" as const;
 
@@ -77,10 +79,6 @@ export function resolveAuditDossier(
   return { status: "ok", runDirectory };
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 type AuditSubjectContext = { sessionManager: { getEntries?(): Iterable<unknown> } };
 
 /**

package/src/engine-detour-tool.ts

@@ -22,8 +22,6 @@ import {
 } from "./engine-detour-usage.ts";
 import { runIdFromRunDirectory } from "./run-terminal-artifacts.ts";
 
-
-
 // #836 r16 class 3: argv required/minItems/element-minLength stay — execute()
 // must obtain the first item as the executable and spawn it (below; #82-98).
 // Root additionalProperties:false is deleted — execute() reads only `argv`.

package/src/engine-detour-usage.ts

@@ -27,6 +27,8 @@ import {
   type RecordPointer,
 } from "./sitian-facade.ts";
 
+import { isRecord } from "./unknown-value.ts";
+
 /** Sitian event kind for one detour-tool call (volume under session/). */
 export const ENGINE_DETOUR_CALL_KIND = "engine-detour-call" as const;
 
@@ -155,10 +157,6 @@ export function reportEngineDetourCall(
   };
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function callFactFromSitianPayload(
   payload: unknown,
   pointer: RecordPointer,

package/src/external-host-turn-loop.ts

@@ -11,6 +11,8 @@ import type {
 } from "./host-contracts.ts";
 import type { PreparedRoleTurn } from "./prepared-role-turn.ts";
 
+import { errorText } from "./unknown-value.ts";
+
 export const EXTERNAL_ROLE_TURN_ROUND_LIMIT = 8 as const;
 
 export type ExternalPreparedTurn = Pick<PreparedRoleTurn, "prompt" | "abortSignal" | "closeRound">;
@@ -103,7 +105,7 @@ export function withExternalHostCleanupFailure(
   cleanupError: unknown,
   name: string,
 ): RoleTurnResult {
-  const message = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+  const message = errorText(cleanupError);
   if (outcome.knownFailure === undefined) {
     return externalHostFailure("session", name, "dispose-failed", { cleanupError: message }, message);
   }

package/src/factory-board.ts

@@ -41,6 +41,7 @@ import {
 } from "./ticket-trajectory.ts";
 import type { BoardSnapshot, SnapshotTicket, TicketIssueState } from "./ticket-snapshot.ts";
 
+import { isRecord, isMissingPathError } from "./unknown-value.ts";
 
 /** Unaccepted latest-run mtime bands (page-visible thresholds). */
 export const UNACCEPTED_FLYING_MS = 2 * 60 * 1000;
@@ -308,14 +309,6 @@ function currentStateLabel(state: TicketCurrentState): string {
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isMissingPathError(error: unknown): boolean {
-  return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
-}
-
 function escapeHtml(text: string): string {
   return text
     .replaceAll("&", "&amp;")

package/src/gatekeeper-role.ts

@@ -14,6 +14,7 @@ import {
 import type { PublicSummonResult } from "./public-role-summons.ts";
 import type { TerminalResult } from "./public-cli/terminal.ts";
 import { runIdFromRunDirectory } from "./run-terminal-artifacts.ts";
+import { isRecord } from "./unknown-value.ts";
 export const INSPECTOR_OUTPUT_TOOL = INSPECTOR_OUTPUT_TOOL_NAME;
 export const NOTARY_OUTPUT_TOOL = REVIEW_SUBMISSION_OUTPUT_TOOL_NAME;
 
@@ -174,20 +175,11 @@ function failureReason(error: unknown): string {
   return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** Original decision bytes — no sentinel replacement (#836). */
 function retainedReceipt(decision: unknown): unknown {
   return decision;
 }
 
-function readRecord(value: unknown): Record<string, unknown> | undefined {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
-  return value as Record<string, unknown>;
-}
-
 /**
  * Read only the conclusion field for queueing (#753).
  * converged | continue | escalate → queue signal + raw receipt.
@@ -206,7 +198,7 @@ function projectOfficerDecision(
   fallbackStatus?: string,
 ): GatekeeperResult {
   const receipt = retainedReceipt(decision);
-  const record = readRecord(decision);
+  const record = isRecord(decision) ? decision : undefined;
   const status =
     (record !== undefined && typeof record.status === "string" ? record.status : undefined)
     ?? fallbackStatus;

package/src/gleaner-left-contracts.ts

@@ -4,6 +4,8 @@
  * No bounce / verdict channel (言不为狱). 原卷保真 (ADR 0055).
  */
 
+import { isRecord } from "./unknown-value.ts";
+
 export const GLEANER_LEFT_OUTPUT_TOOL_NAME = "ak_gleaner_left_output";
 
 /** Internal transport: comparison-base revision for the unanchored merge-candidate diff. */
@@ -26,7 +28,7 @@ export type GleanerLeftOutput = {
 };
 
 export function validateRecordedGleanerLeftOutput(value: unknown): GleanerLeftOutput {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+  if (!isRecord(value)) {
     throw new Error("Gleaner-left output has no execution discriminator");
   }
   let status: unknown;

package/src/headless-host/description.ts

@@ -6,6 +6,8 @@
  */
 import type { HostIdentityDescription } from "../host-descriptions.ts";
 
+import { isRecord } from "../unknown-value.ts";
+
 /** Claude Code print-mode (#645). */
 export type ClaudePrintHostDescription = HostIdentityDescription & Readonly<{
   protocol: "claude-print";
@@ -167,7 +169,7 @@ export function closeJsonSchemaForCodex(
   schema: Readonly<Record<string, unknown>>,
 ): Record<string, unknown> {
   const closed = closeSchemaNode(schema) as Record<string, unknown>;
-  const existingDefs = isPlainObject(closed.$defs)
+  const existingDefs = isRecord(closed.$defs)
     ? (closed.$defs as Record<string, unknown>)
     : {};
   return {
@@ -179,14 +181,9 @@ export function closeJsonSchemaForCodex(
   };
 }
 
-/** Shared plain-object guard for headless host schema/event reduction. */
-export function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** Pure null leaf only — composite type|null is stripped in-leaf, not dropped whole. */
 function isPureNullTypeSchema(value: unknown): boolean {
-  if (!isPlainObject(value)) return false;
+  if (!isRecord(value)) return false;
   if (value.type === "null") return true;
   if (Array.isArray(value.type) && value.type.length > 0 && value.type.every((t) => t === "null")) {
     return true;
@@ -199,7 +196,7 @@ function isPureNullTypeSchema(value: unknown): boolean {
  * Required edges keep the non-null type(s); optional edges re-add null once.
  */
 function stripNullFromLeafType(leaf: unknown): unknown {
-  if (!isPlainObject(leaf) || !Array.isArray(leaf.type)) return leaf;
+  if (!isRecord(leaf) || !Array.isArray(leaf.type)) return leaf;
   const nonNull = leaf.type.filter((t) => t !== "null");
   if (nonNull.length === leaf.type.length) return leaf;
   if (nonNull.length === 0) return { ...leaf, type: "null" };
@@ -213,7 +210,7 @@ function stripNullFromLeafType(leaf: unknown): unknown {
  * lack `type`; strict structured output rejects those intermediate nodes.
  */
 function flattenUnionLeaves(schema: unknown): unknown[] {
-  if (!isPlainObject(schema)) return [schema];
+  if (!isRecord(schema)) return [schema];
   if (Array.isArray(schema.anyOf)) {
     return schema.anyOf.flatMap(flattenUnionLeaves);
   }
@@ -233,7 +230,7 @@ function nonNullLeaves(schema: unknown): unknown[] {
  */
 function closePropertySchema(schema: unknown, optional: boolean): unknown {
   const description =
-    isPlainObject(schema) && typeof schema.description === "string"
+    isRecord(schema) && typeof schema.description === "string"
       ? { description: schema.description }
       : {};
   const leaves = nonNullLeaves(schema).map(closeSchemaNode);
@@ -242,10 +239,10 @@ function closePropertySchema(schema: unknown, optional: boolean): unknown {
     const closed = leaves.length === 1 ? leaves[0] : { anyOf: leaves };
     // Codex strict does not allow sibling keys on $ref; put property guidance
     // on an enclosing schema instead of losing it or weakening the free-JSON ref.
-    if (isPlainObject(closed) && typeof closed.$ref === "string") {
+    if (isRecord(closed) && typeof closed.$ref === "string") {
       return { anyOf: [closed], ...description };
     }
-    return isPlainObject(closed) ? { ...closed, ...description } : closed;
+    return isRecord(closed) ? { ...closed, ...description } : closed;
   }
   return { anyOf: [...leaves, { type: "null" }], ...description };
 }
@@ -258,7 +255,7 @@ function closePropertySchema(schema: unknown, optional: boolean): unknown {
 function ensureTypedLeaf(schema: Record<string, unknown>): Record<string, unknown> {
   if (schema.type !== undefined) return schema;
   if (typeof schema.$ref === "string") return schema;
-  if (isPlainObject(schema.properties) || schema.additionalProperties !== undefined) {
+  if (isRecord(schema.properties) || schema.additionalProperties !== undefined) {
     return { ...schema, type: "object" };
   }
   if (schema.items !== undefined) {
@@ -287,7 +284,7 @@ function originalRequiredNames(node: Record<string, unknown>): ReadonlySet<strin
 }
 
 function closeSchemaNode(node: unknown): unknown {
-  if (!isPlainObject(node)) return node;
+  if (!isRecord(node)) return node;
 
   // Already a ref (free-JSON leaf or pre-existing) — do not retype.
   if (typeof node.$ref === "string") return node;
@@ -305,13 +302,13 @@ function closeSchemaNode(node: unknown): unknown {
   if (node.items !== undefined) {
     out.items = closeSchemaNode(node.items);
   }
-  if (isPlainObject(node.$defs)) {
+  if (isRecord(node.$defs)) {
     out.$defs = Object.fromEntries(
       Object.entries(node.$defs).map(([key, value]) => [key, closeSchemaNode(value)]),
     );
   }
 
-  const hasProperties = isPlainObject(node.properties);
+  const hasProperties = isRecord(node.properties);
   const isObjectType =
     node.type === "object"
     || (Array.isArray(node.type) && node.type.includes("object"))
@@ -351,10 +348,10 @@ function closeSchemaNode(node: unknown): unknown {
 function stringEnvironment(value: unknown): Record<string, string> | undefined {
   const entries = Array.isArray(value)
     ? value.flatMap((item) => {
-        if (!isPlainObject(item) || typeof item.name !== "string" || typeof item.value !== "string") return [];
+        if (!isRecord(item) || typeof item.name !== "string" || typeof item.value !== "string") return [];
         return [[item.name, item.value] as const];
       })
-    : isPlainObject(value)
+    : isRecord(value)
       ? Object.entries(value).filter((entry): entry is [string, string] => typeof entry[1] === "string")
       : [];
   return entries.length === 0 ? undefined : Object.fromEntries(entries);

package/src/headless-host/role-turn-host.ts

@@ -36,11 +36,12 @@ import {
   headlessTurnArgs,
   isClaudePrintDescription,
   isCodexExecDescription,
-  isPlainObject,
   type HeadlessHostDescription,
 } from "./description.ts";
 import { NAVIGATOR_OUTPUT_TOOL_NAME } from "../package-contracts/navigator-output.ts";
 
+import { errorText, isRecord } from "../unknown-value.ts";
+
 export type HeadlessRoleTurnHostConfig = Readonly<{
   description: HeadlessHostDescription;
   sessionIdentity: SessionIdentityAuthority;
@@ -68,7 +69,7 @@ export type HeadlessCliResult = Readonly<{
  * envelope without stream-json `type`). Intermediate stream-json events are not.
  */
 function isHeadlessResultCandidate(value: unknown): value is HeadlessCliResult {
-  if (!isPlainObject(value)) return false;
+  if (!isRecord(value)) return false;
   const record = value as HeadlessCliResult & { type?: unknown };
   return record.type === undefined
     || record.type === "result"
@@ -131,11 +132,11 @@ function createCodexExecTurnObserver(): {
 
   return {
     observe(value) {
-      if (!isPlainObject(value)) return;
+      if (!isRecord(value)) return;
       const type = typeof value.type === "string" ? value.type : undefined;
       if (type === "thread.started" && typeof value.thread_id === "string" && value.thread_id !== "") {
         threadId = value.thread_id;
-      } else if (type === "item.completed" && isPlainObject(value.item)) {
+      } else if (type === "item.completed" && isRecord(value.item)) {
         if (value.item.type === "agent_message" && typeof value.item.text === "string") {
           finalMessage = value.item.text;
         }
@@ -161,7 +162,7 @@ function createCodexExecTurnObserver(): {
 
 function formatCodexFailurePayload(payload: unknown): string {
   if (typeof payload === "string" && payload.trim() !== "") return payload;
-  if (isPlainObject(payload)) {
+  if (isRecord(payload)) {
     if (typeof payload.message === "string" && payload.message.trim() !== "") return payload.message;
     try {
       return JSON.stringify(payload);
@@ -198,7 +199,7 @@ function resolveGitCommonDir(cwd: string): string | undefined {
       encoding: "utf8",
     });
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = errorText(error);
     throw new Error(`git rev-parse --git-common-dir failed: ${message}`);
   }
   if (result.error !== undefined) {
@@ -487,7 +488,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
               ...(gitCommonDir === undefined ? {} : { writableRoots: [gitCommonDir] }),
             });
           } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = errorText(error);
             return {
               status: "terminal",
               result: failure("session", "HeadlessArgvFailure", "argv-failed", { diagnostic: message }, message),
@@ -559,7 +560,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
           } catch (error) {
             if (childExited) exitedSessionId = (codex ? codexObserver?.result().threadId : undefined) ?? sessionId;
             if (isHostAbortedError(error)) throw error;
-            const message = error instanceof Error ? error.message : String(error);
+            const message = errorText(error);
             const observedHostFailure = codexObserver?.result().failureDiagnostic;
             if (observedHostFailure !== undefined) {
               return {
@@ -604,7 +605,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
               } catch (error) {
                 // The host failure remains primary; retain persistence failure as
                 // secondary typed evidence instead of replacing the terminal.
-                sessionBindingDiagnostic = error instanceof Error ? error.message : String(error);
+                sessionBindingDiagnostic = errorText(error);
               }
             }
 

package/src/host-session-record.ts

@@ -26,6 +26,8 @@ import type { RoleTurnContinuation } from "./host-contracts.ts";
 import { sitianReport } from "./sitian-facade.ts";
 import type { SitianRecordInput } from "./sitian-contracts.ts";
 
+import { errorText } from "./unknown-value.ts";
+
 /** Volume category under `<run>/session/<kind>/records.jsonl`. */
 export const HOST_SESSION_RECORD_KIND = "host-session" as const;
 
@@ -269,7 +271,7 @@ export function copyAndRecordHostDossier(options: {
       payload: {
         type: "native-session-warning",
         sessionId: options.sessionId,
-        error: error instanceof Error ? error.message : String(error),
+        error: errorText(error),
       },
     });
     return;
@@ -334,7 +336,7 @@ export function copyAndRecordHostDossier(options: {
         landingPath,
         ordinal,
         sessionId: options.sessionId,
-        error: lastError instanceof Error ? lastError.message : String(lastError),
+        error: errorText(lastError),
       },
     });
   }

package/src/inspector-contracts.ts

@@ -5,6 +5,7 @@
  */
 
 import { REVIEW_QUEUE_STATUSES, REVIEW_SUBMISSION_OUTPUT_TOOL_NAME } from "./review-submission.ts";
+import { isRecord } from "./unknown-value.ts";
 
 export const INSPECTOR_OUTPUT_TOOL_NAME: string = REVIEW_SUBMISSION_OUTPUT_TOOL_NAME;
 export const INSPECTOR_SOURCE_RUN_FLAG = {
@@ -21,7 +22,7 @@ export type InspectorOutput =
   | { readonly status: "escalate"; readonly reason?: unknown; readonly findings?: unknown };
 
 export function validateRecordedInspectorOutput(value: unknown): InspectorOutput {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+  if (!isRecord(value)) {
     throw new Error("Inspector output has no execution discriminator");
   }
   let status: unknown;

package/src/ledger-session-read.ts

@@ -4,6 +4,8 @@
  */
 import { readFile } from "node:fs/promises";
 
+import { isRecord } from "./unknown-value.ts";
+
 export type LedgerSessionRow = Record<string, unknown>;
 
 /**
@@ -32,10 +34,6 @@ export class LedgerSessionJsonlError extends Error {
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * One physical JSONL line as the single kernel saw it.
  * `row` present = syntactically complete session object at that 1-based line.
@@ -339,4 +337,3 @@ export function intervalRowsAroundAnchor(
   return { rows: rows.slice(start, end), closed: end < rows.length };
 }
 
-