@akagilnc/pi-workflow-roles 0.1.5368 → 0.1.5382

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

@@ -1,10 +1,14 @@
-import type { RoleHost, HostContext, HostToolResult } from "./host-contracts.ts";
+import type { RoleHost, HostContext } from "./host-contracts.ts";
+import { registerFiledSubmissionTool } from "./filed-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import { ComplianceResponseRetentionError } from "./compliance-transport.ts";
 import { DOCTOR_CANDIDATE_ENTRY_TYPE } from "./dossier-resolution.ts";
-import { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_DESCRIPTION, DOCTOR_OUTPUT_TOOL_NAME, DoctorEvidenceStore, doctorEvidenceReadSchema, doctorSubmissionSchema, validateDoctorOutput, type DoctorCase } from "./doctor-contracts.ts";
+import { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME, DoctorEvidenceStore, doctorEvidenceReadSchema, validateDoctorOutput, type DoctorCase } from "./doctor-contracts.ts";
 
 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 +23,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 });
     }
   }
 }
@@ -34,15 +38,18 @@ export function createDoctorRoleRuntime(pi: RoleHost, dependencies: DoctorRoleDe
   let activation: { soul: string; patient: DoctorCase; store: DoctorEvidenceStore } | undefined; let registered = false; pi.registerFlag(DOCTOR_CASE_FLAG.name, DOCTOR_CASE_FLAG.definition);
   return { async activate() { const path = pi.getFlag(DOCTOR_CASE_FLAG.name); if (typeof path !== "string" || !path.trim()) throw new Error("Doctor requires --ak-doctor-case"); const soul = (await dependencies.loadSoul()).trim(); if (!soul) throw new Error("Doctor soul is empty"); const patient = await dependencies.loadCase(path); activation = { soul, patient, store: new DoctorEvidenceStore(patient) };
     if (!registered) { registered = true; pi.registerTool({ name: DOCTOR_EVIDENCE_TOOL_NAME, label: "太医署证据", description: "分页读取留存的 Pi session 字节。", parameters: doctorEvidenceReadSchema, async execute(_id: string, params: { evidenceId: string; offset?: number; limit?: number }) { if (!activation) throw new Error("太医署未激活"); const details = activation.store.read(params.evidenceId, params.offset, params.limit); return { content: [{ type: "text" as const, text: JSON.stringify(details) }], details }; } });
-      pi.registerTool({ name: DOCTOR_OUTPUT_TOOL_NAME, label: "太医署输出", description: DOCTOR_OUTPUT_TOOL_DESCRIPTION, parameters: doctorSubmissionSchema, async execute(id: string, params: unknown, _signal: AbortSignal | undefined, _update: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> {
-        if (!activation) throw new Error("太医署未激活");
-        const active = activation;
-        const testimony = validateDoctorOutput(params, active.patient, active.store);
-        try {
-          appendCandidate(ctx, { version: 1, testimony, cost: active.patient.cost, readRecord: active.store.readRecord(), patientIdentity: active.patient.identity });
-        } catch (error) { host.failInfrastructure(error, ctx, id); }
-        return { content: [], details: testimony, terminate: true };
-      } });
+      registerFiledSubmissionTool(pi, roleSubmissionDeclaration("doctor"), {
+        readyError: () => (activation === undefined ? "太医署未激活" : undefined),
+        beforeAccept: async ({ toolCallId, parameters, ctx }) => {
+          if (activation === undefined) throw new Error("太医署未激活");
+          const active = activation;
+          const testimony = validateDoctorOutput(parameters, active.patient, active.store);
+          try {
+            appendCandidate(ctx, { version: 1, testimony, cost: active.patient.cost, readRecord: active.store.readRecord(), patientIdentity: active.patient.identity });
+          } catch (error) { host.failInfrastructure(error, ctx, toolCallId); }
+          return testimony;
+        },
+      });
       pi.on("before_agent_start", (event) => { if (!activation) throw new Error("太医署未激活"); const catalog = { version: activation.patient.version, identity: activation.patient.identity, admittedMetrics: { cost: activation.patient.cost }, lawfulTargetKeys: ["case", ...activation.patient.cost.invocations.sources], evidence: activation.patient.evidence.map(({ id, kind, sha256, byteLength, contentLength }) => ({ id, kind, sha256, byteLength, contentLength })) }; return { systemPrompt: `${event.systemPrompt}\n\n<doctor_soul>\n${activation.soul}\n</doctor_soul>\n\n<doctor_case>\n${JSON.stringify(catalog)}\n</doctor_case>` }; }); }
     const required = [DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME]; const names = pi.getAllTools().map((tool) => tool.name); for (const name of required) if (names.filter((item) => item === name).length !== 1) throw new Error(`Doctor required tool collision or missing: ${name}`); pi.setActiveTools(required); const active = pi.getActiveTools?.() ?? required; if (active.length !== 2 || !required.every((name) => active.includes(name))) throw new Error("Doctor active tool narrowing failed"); } };
 }

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/filed-submission.ts

@@ -0,0 +1,44 @@
+import type { HostContext, HostToolResult, RoleHost } from "./host-contracts.ts";
+import type { RoleSubmissionDeclaration } from "./role-submission-declarations.ts";
+
+export type FiledSubmissionBeforeAccept = (input: {
+  readonly toolCallId: string;
+  readonly parameters: unknown;
+  readonly signal: AbortSignal | undefined;
+  readonly ctx: HostContext;
+}) => Promise<unknown>;
+
+/**
+ * One host-neutral submission execute for every public seat.
+ * Records nothing itself — the ledger seam already appends the original payload.
+ * Ends this tool call. Does not summon an auditor and does not end the role run.
+ * Shape is not an admission gate (ADR 0055). Seat reminders stay on beforeAccept.
+ */
+export function registerFiledSubmissionTool(
+  roleHost: RoleHost,
+  tool: RoleSubmissionDeclaration,
+  options: {
+    readonly readyError: () => string | undefined;
+    readonly beforeAccept?: FiledSubmissionBeforeAccept;
+  },
+): void {
+  roleHost.registerTool({
+    name: tool.name,
+    label: tool.label,
+    description: tool.description,
+    ...(tool.promptSnippet === undefined ? {} : { promptSnippet: tool.promptSnippet }),
+    parameters: tool.parameters as never,
+    async execute(toolCallId, parameters, signal, _onUpdate, ctx): Promise<HostToolResult<unknown>> {
+      const blocked = options.readyError();
+      if (blocked !== undefined) throw new Error(blocked);
+      const projected = options.beforeAccept === undefined
+        ? undefined
+        : await options.beforeAccept({ toolCallId, parameters, signal, ctx });
+      return {
+        content: [],
+        details: projected === undefined ? parameters : projected,
+        terminate: true as const,
+      };
+    },
+  });
+}

package/src/gatekeeper-role.ts

@@ -7,13 +7,12 @@ import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 import { GatekeeperDecisionError, receivedDiscriminator, unreadableDiscriminatorNotice } from "./submission-errors.ts";
 import { INSPECTOR_OUTPUT_TOOL_NAME } from "./inspector-contracts.ts";
 import { REVIEW_QUEUE_STATUSES, REVIEW_SUBMISSION_OUTPUT_TOOL_NAME } from "./review-submission.ts";
-import {
-  GATEKEEPER_OUTPUT_TOOL_NAME,
-  gatekeeperOutputSchema,
-} from "./package-contracts/gatekeeper-output.ts";
+import { GATEKEEPER_OUTPUT_TOOL_NAME } from "./package-contracts/gatekeeper-output.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 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;
 
@@ -157,13 +156,7 @@ export type SubmissionGateHostActions = {
  * registration envelope — src/role-runtime.ts (ADR 0018). Schema authority is
  * the shared contract module (with infrastructure-failure declaration).
  */
-export const GATEKEEPER_TOOL_SPEC = {
-  name: GATEKEEPER_OUTPUT_TOOL_NAME,
-  label: "门下省决议",
-  description: "门下省终局决议。status 为 dispatch 或 pass。",
-  promptSnippet: "门下省决议",
-  parameters: gatekeeperOutputSchema,
-} as const;
+export const GATEKEEPER_TOOL_SPEC = roleSubmissionDeclaration("gatekeeper");
 
 export type GatekeeperRuntimeDependencies = {
   loadSoul(): Promise<string>;
@@ -174,20 +167,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,10 +190,10 @@ function projectOfficerDecision(
   fallbackStatus?: string,
 ): GatekeeperResult {
   const receipt = retainedReceipt(decision);
-  const record = readRecord(decision);
-  const status =
-    (record !== undefined && typeof record.status === "string" ? record.status : undefined)
-    ?? fallbackStatus;
+  const record = isRecord(decision) ? decision : undefined;
+  const status = record !== undefined && Object.hasOwn(record, "status")
+    ? receivedDiscriminator(record, "status")
+    : fallbackStatus;
   const queueStatus = typeof status === "string" ? reviewQueueStatus(status) : undefined;
   if (queueStatus === "converged") {
     return { status: "converged", officer, receipt };

package/src/gleaner-left-contracts.ts

@@ -4,8 +4,36 @@
  * No bounce / verdict channel (言不为狱). 原卷保真 (ADR 0055).
  */
 
+import { Type } from "typebox";
+
+import { openToolObject } from "./open-tool-schema.ts";
+import { withTerminatingOutputDeclarations } from "./package-contracts/terminating-infrastructure.ts";
+import { isRecord } from "./unknown-value.ts";
+
 export const GLEANER_LEFT_OUTPUT_TOOL_NAME = "ak_gleaner_left_output";
 
+// #836 r16 class 1: pointer/statement are LLM/human-read narrative content — no
+// code branches on their presence.
+// #1134: `status` alone is the trajectory field (src/gleaner-left-contracts.ts:38
+// recognizes completed to settle); its word rides the description. findings is
+// narrative content declared name + semantic description only — the array type
+// and the nested pointer/statement object shape are deleted, because the package
+// declaration IS the host's pre-dispatch validator. An empty findings list stays
+// a lawful completion; an omitted one is now expressible too.
+export const gleanerLeftOutputSchema = withTerminatingOutputDeclarations(
+  openToolObject(
+    Type.Object({
+      status: Type.Unknown({
+        description: "completed",
+      }),
+      findings: Type.Unknown({
+        description:
+          "弹章列表；每条可含 pointer（文件/行指针）与 statement（疑点陈述），原样留存。空列表合法完局；机器不判弹章是否成立。",
+      }),
+    }),
+  ),
+);
+
 /** Internal transport: comparison-base revision for the unanchored merge-candidate diff. */
 export const GLEANER_LEFT_BASE_FLAG = {
   name: "ak-gleaner-left-base",
@@ -26,7 +54,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;
@@ -40,4 +68,3 @@ export function validateRecordedGleanerLeftOutput(value: unknown): GleanerLeftOu
   }
   throw new Error("Gleaner-left output has no execution discriminator");
 }
-

package/src/gleaner-left-role.ts

@@ -1,42 +1,20 @@
 import type { Static } from "typebox";
-import { Type } from "typebox";
 
-import { openToolObject } from "./open-tool-schema.ts";
-import { withTerminatingOutputDeclarations } from "./package-contracts/terminating-infrastructure.ts";
 import {
   GLEANER_LEFT_OUTPUT_TOOL_NAME,
+  gleanerLeftOutputSchema,
   validateRecordedGleanerLeftOutput,
   type GleanerLeftOutput,
 } from "./gleaner-left-contracts.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 
 export {
   GLEANER_LEFT_OUTPUT_TOOL_NAME,
+  gleanerLeftOutputSchema,
 } from "./gleaner-left-contracts.ts";
 export type { GleanerLeftOutput };
 export { validateRecordedGleanerLeftOutput };
 
-// #836 r16 class 1: pointer/statement are LLM/human-read narrative content — no
-// code branches on their presence.
-// #1134: `status` alone is the trajectory field (src/gleaner-left-contracts.ts:38
-// recognizes completed to settle); its word rides the description. findings is
-// narrative content declared name + semantic description only — the array type
-// and the nested pointer/statement object shape are deleted, because the package
-// declaration IS the host's pre-dispatch validator. An empty findings list stays
-// a lawful completion; an omitted one is now expressible too.
-export const gleanerLeftOutputSchema = withTerminatingOutputDeclarations(
-  openToolObject(
-    Type.Object({
-      status: Type.Unknown({
-        description: "completed",
-      }),
-      findings: Type.Unknown({
-        description:
-          "弹章列表；每条可含 pointer（文件/行指针）与 statement（疑点陈述），原样留存。空列表合法完局；机器不判弹章是否成立。",
-      }),
-    }),
-  ),
-);
-
 export type GleanerLeftOutputParameters = Static<typeof gleanerLeftOutputSchema>;
 
 export type GleanerLeftRuntimeDependencies = {
@@ -46,10 +24,4 @@ export type GleanerLeftRuntimeDependencies = {
 /**
  * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
  */
-export const GLEANER_LEFT_TOOL_SPEC = {
-  name: GLEANER_LEFT_OUTPUT_TOOL_NAME,
-  label: "左拾遗输出",
-  description: "左拾遗弹章。",
-  promptSnippet: "左拾遗弹章",
-  parameters: gleanerLeftOutputSchema,
-} as const;
+export const GLEANER_LEFT_TOOL_SPEC = roleSubmissionDeclaration("gleaner-left");

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);
               }
             }