@akagilnc/pi-workflow-roles 0.1.3644 → 0.1.3652

package/dist/doctor-role.js

@@ -0,0 +1,74 @@
+import { disposeComplianceDecision } from "./audit-escalation.js";
+import { ComplianceResponseRetentionError } from "./compliance-transport.js";
+import { DOCTOR_CANDIDATE_ENTRY_TYPE } from "./dossier-resolution.js";
+import { DOCTOR_ACCEPTED_AUDIT_NO_RECEIPT_TEXT, DOCTOR_ACCEPTED_TEXT, DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_DESCRIPTION, DOCTOR_OUTPUT_TOOL_NAME, DoctorEvidenceStore, doctorEvidenceReadSchema, doctorSubmissionSchema, validateDoctorOutput } from "./doctor-contracts.js";
+import { sitianReport } from "./sitian-facade.js";
+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>/issues/<n>/runs directory", type: "string" } };
+function appendCandidate(ctx, data) {
+    try {
+        sitianReport({
+            level: "event",
+            kind: "candidate",
+            cwd: ctx.cwd,
+            sessionParent: ctx.sessionManager.getSessionFile(),
+            payload: data,
+            source: "doctor-role",
+        });
+    }
+    catch (error) {
+        throw new ComplianceResponseRetentionError(`太医署候选留存失败: ${error instanceof Error ? error.message : String(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 });
+        }
+    }
+}
+export function createDoctorRoleRuntime(pi, dependencies, host) {
+    let activation;
+    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, params) { if (!activation)
+                        throw new Error("太医署未激活"); const details = activation.store.read(params.evidenceId, params.offset, params.limit); return { content: [{ type: "text", text: JSON.stringify(details) }], details }; } });
+                pi.registerTool({ name: DOCTOR_OUTPUT_TOOL_NAME, label: "太医署输出", description: DOCTOR_OUTPUT_TOOL_DESCRIPTION, parameters: doctorSubmissionSchema, async execute(id, params, signal, _update, ctx) { if (!activation)
+                        throw new Error("太医署未激活"); const testimony = validateDoctorOutput(params, activation.patient, activation.store); try {
+                        appendCandidate(ctx, { version: 1, testimony, readRecord: activation.store.readRecord(), patientIdentity: activation.patient.identity });
+                    }
+                    catch (error) {
+                        host.failInfrastructure(error, ctx, id);
+                    } let audit; try {
+                        audit = await dependencies.auditCompliance(signal === undefined ? { context: ctx } : { context: ctx, signal });
+                    }
+                    catch (error) {
+                        host.failInfrastructure(error, ctx, id);
+                    } const details = testimony.status === "completed" ? { ...testimony, cost: activation.patient.cost } : testimony; const acceptedDetails = details; return disposeComplianceDecision(audit, { pass: (usage) => ({ content: [{ type: "text", text: DOCTOR_ACCEPTED_TEXT }], details: acceptedDetails, terminate: true, ...(usage === undefined ? {} : { usage }) }), noReceipt: (auditNoReceipt, usageProjection) => ({ content: [{ type: "text", text: DOCTOR_ACCEPTED_AUDIT_NO_RECEIPT_TEXT }], details: { ...acceptedDetails, auditNoReceipt }, terminate: true, ...usageProjection }), received: (auditReceived, usageProjection) => ({ content: [{ type: "text", text: DOCTOR_ACCEPTED_TEXT }], details: { ...acceptedDetails, audit: auditReceived.reply }, terminate: true, ...usageProjection }), bounce: (violations) => { throw new Error(`太医署回执违 soul：${violations.join("; ")}`); }, escalate: (result) => result }, acceptedDetails); } });
+                pi.on("before_agent_start", (event) => { if (!activation)
+                    throw new Error("太医署未激活"); const catalog = { version: activation.patient.version, identity: activation.patient.identity, admittedMetrics: { provenance: "由留存 session 字节推导，封入受理回执。", 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/dist/fixer-bash-seatbelt.js

@@ -0,0 +1,13 @@
+/** Exact case-sensitive substring literals blocked on Fixer bash (ADR 0008). */
+export const FIXER_BASH_FORBIDDEN_LITERALS = [
+    "rm -rf",
+    "git reset --hard",
+    "git clean",
+    "git checkout --",
+];
+export function matchFixerBashForbiddenLiteral(command) {
+    return FIXER_BASH_FORBIDDEN_LITERALS.find((literal) => command.includes(literal));
+}
+export function fixerBashSeatbeltDenyReason(matched) {
+    return `修内司 bash 拦截：命中禁用字面量 ${matched}`;
+}

package/dist/gatekeeper-pass-envelope.js

@@ -0,0 +1,72 @@
+import { bookDirectOfficerRunPointer } from "./archivist-record-entry.js";
+import { GatekeeperDecisionError, GatekeeperEscalationError, projectGatekeeperRun, } from "./gatekeeper-role.js";
+import { sessionFileFromPublicSummon } from "./session-assistant-usage.js";
+/**
+ * Book a typed pointer under parent session/auditor-roles (archivist-owned write).
+ * Offline mocks without a real session leave no nested volume (lawful zero).
+ */
+function bookDirectOfficerPointer(context, officer, result, summoned) {
+    if (result.status !== "pass"
+        && result.status !== "bounce"
+        && result.status !== "escalate"
+        && result.status !== "unreadable") {
+        return;
+    }
+    const parentFile = context.sessionManager?.getSessionFile?.();
+    if (typeof parentFile !== "string" || parentFile.trim() === "")
+        return;
+    const sessionFile = sessionFileFromPublicSummon(summoned);
+    if (sessionFile === undefined) {
+        // No independent 正本 to point at — do not synthesize a parallel session.
+        return;
+    }
+    bookDirectOfficerRunPointer({
+        parentSessionFile: parentFile,
+        officer,
+        sessionFile,
+        ...(typeof summoned.runDirectory === "string" && summoned.runDirectory.trim() !== ""
+            ? { runDirectory: summoned.runDirectory }
+            : {}),
+    });
+}
+/**
+ * Shared envelope: project gate, book officer pointer, map onto host actions.
+ * unreadable = parent stands (ADR 0055); never mechanical NonPass reject.
+ */
+export async function requireGatekeeperPass(options) {
+    const projected = await projectGatekeeperRun({
+        context: options.context,
+        subject: options.subject,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.summonOfficer === undefined ? {} : { summonOfficer: options.summonOfficer }),
+    });
+    const gatekeeper = projected.result;
+    // Envelope-owned pointer book. Failure is host infrastructure — single face.
+    if (projected.summoned !== undefined) {
+        try {
+            bookDirectOfficerPointer(options.context, projected.officer, gatekeeper, projected.summoned);
+        }
+        catch (error) {
+            options.hostActions.failInfrastructure(error, options.context, options.toolCallId);
+        }
+    }
+    if (gatekeeper.status === "pass")
+        return;
+    // ADR 0055 / #675: shape-unreadable officer output must not mechanically reject parent.
+    if (gatekeeper.status === "unreadable")
+        return;
+    if (gatekeeper.status === "transport_failure") {
+        const error = new Error(`交卷闸 transport_failure（${gatekeeper.stage}）：${gatekeeper.reason}`);
+        error.stage = gatekeeper.stage;
+        error.reason = gatekeeper.reason;
+        if (gatekeeper.submission !== undefined)
+            error.submission = gatekeeper.submission;
+        options.hostActions.failInfrastructure(error, options.context, options.toolCallId);
+    }
+    if (gatekeeper.status === "escalate") {
+        throw new GatekeeperEscalationError(gatekeeper);
+    }
+    // bounce / no_receipt: typed non-pass — envelope owns execute→tool_result bridge.
+    options.hostActions.bindSubmissionNonPass(options.toolCallId, gatekeeper);
+    throw new GatekeeperDecisionError(gatekeeper);
+}

package/dist/gleaner-left-contracts.js

@@ -22,16 +22,9 @@ function validateRecordedGleanerLeftOutput(value) {
   }
   throw new Error("Gleaner-left output has no execution discriminator");
 }
-function gleanerLeftDecisiveFacts(output) {
-  const facts = { status: output.status };
-  const findings = output.findings;
-  if (Array.isArray(findings)) facts.findings = findings;
-  return facts;
-}
 export {
   GLEANER_LEFT_ACCEPTED_TEXT,
   GLEANER_LEFT_BASE_FLAG,
   GLEANER_LEFT_OUTPUT_TOOL_NAME,
-  gleanerLeftDecisiveFacts,
   validateRecordedGleanerLeftOutput
 };

package/dist/gleaner-left-role.js

@@ -0,0 +1,26 @@
+import { Type } from "typebox";
+import { openToolObject } from "./open-tool-schema.js";
+import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.js";
+import { GLEANER_LEFT_OUTPUT_TOOL_NAME, validateRecordedGleanerLeftOutput, } from "./gleaner-left-contracts.js";
+export { GLEANER_LEFT_ACCEPTED_TEXT, GLEANER_LEFT_OUTPUT_TOOL_NAME, } from "./gleaner-left-contracts.js";
+export { validateRecordedGleanerLeftOutput };
+/** 左拾遗弹章交卷形状；形状指引，非 schema 闸。 */
+export const gleanerLeftOutputSchema = withInfrastructureFailureDeclaration(openToolObject(Type.Object({
+    status: Type.Unknown({
+        description: "completed — 形状指引，非 schema 闸",
+    }),
+    findings: Type.Array(Type.Object({
+        pointer: Type.String({ description: "文件/行指针" }),
+        statement: Type.String({ description: "疑点陈述" }),
+    }, { additionalProperties: true, description: "一条弹章" }), { description: "弹章列表；空列表合法完局" }),
+})));
+/**
+ * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
+ */
+export const GLEANER_LEFT_TOOL_SPEC = {
+    name: GLEANER_LEFT_OUTPUT_TOOL_NAME,
+    label: "左拾遗输出",
+    description: "左拾遗弹章。",
+    promptSnippet: "左拾遗弹章",
+    parameters: gleanerLeftOutputSchema,
+};

package/dist/inspector-contracts.js

@@ -15,12 +15,8 @@ function validateRecordedInspectorOutput(value) {
   }
   throw new Error("Inspector output has no execution discriminator");
 }
-function inspectorDecisiveFacts(output) {
-  return { ...output };
-}
 export {
   INSPECTOR_ACCEPTED_TEXT,
   INSPECTOR_OUTPUT_TOOL_NAME,
-  inspectorDecisiveFacts,
   validateRecordedInspectorOutput
 };

package/dist/inspector-role.js

@@ -0,0 +1,29 @@
+import { Type } from "typebox";
+import { openToolObject } from "./open-tool-schema.js";
+import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.js";
+import { INSPECTOR_ACCEPTED_TEXT, INSPECTOR_OUTPUT_TOOL_NAME, validateRecordedInspectorOutput, } from "./inspector-contracts.js";
+export { INSPECTOR_ACCEPTED_TEXT, INSPECTOR_OUTPUT_TOOL_NAME, };
+export { INSPECTOR_OUTPUT_TOOL_NAME as INSPECTOR_OUTPUT_TOOL };
+export { validateRecordedInspectorOutput };
+/** 察院事后察举交卷形状；形状指引，非 schema 闸。 */
+export const inspectorOutputSchema = withInfrastructureFailureDeclaration(openToolObject(Type.Object({
+    status: Type.Unknown({
+        description: "pass | bounce | escalate — 形状指引，非 schema 闸",
+    }),
+    findings: Type.Unknown({
+        description: "随交卷留存的问题记录",
+    }),
+    reason: Type.Optional(Type.Unknown({
+        description: "status 为 escalate 时的上呈理由",
+    })),
+})));
+/**
+ * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
+ */
+export const INSPECTOR_TOOL_SPEC = {
+    name: INSPECTOR_OUTPUT_TOOL_NAME,
+    label: "察院输出",
+    description: "察院终局回执，状态为 pass、bounce 或 escalate。",
+    promptSnippet: "察院终局回执",
+    parameters: inspectorOutputSchema,
+};

package/dist/judge-role.js

@@ -0,0 +1,106 @@
+import { stringEnum } from "./host-contracts.js";
+import { Type } from "typebox";
+import { disposeComplianceDecision } from "./audit-escalation.js";
+import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.js";
+import { JUDGE_ACCEPTED_AUDIT_NO_RECEIPT_TEXT, JUDGE_ACCEPTED_TEXT, JUDGE_OUTPUT_TOOL_NAME, validateAcceptedJudgeDetails, } from "./package-contracts/judge-output.js";
+export { JUDGE_OUTPUT_TOOL_NAME };
+export const judgeVerdictSchema = withInfrastructureFailureDeclaration(Type.Object({
+    judgeStatus: stringEnum(["converged", "continue", "escalate"], { description: "converged | continue | escalate — 形状指引，非 schema 闸" }),
+    fix: Type.Optional(Type.Object({ summary: Type.String({ minLength: 1, description: "continue 时的补救摘要" }) }, { additionalProperties: false, description: "continue 时的补救说明" })),
+    classes: Type.Optional(Type.Array(Type.Object({
+        name: Type.String({ minLength: 1 }),
+        owner: Type.String({ minLength: 1 }),
+        boundary: Type.String({ minLength: 1 }),
+        disposition: Type.String({ minLength: 1 }),
+    }, { additionalProperties: false }), { minItems: 1, description: "已裁决 finding 类及其 owner 与修理边界" })),
+    note: Type.Optional(Type.String({ minLength: 1, description: "可选裁决附注" })),
+    evidence: Type.Optional(Type.Unknown({ description: "留存的裁决证据" })),
+    decisionGate: Type.Optional(Type.Object({
+        question: Type.String({ minLength: 1 }),
+        options: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+    }, { additionalProperties: false, description: "需人权威处置的问题与选项" })),
+}, { additionalProperties: true }));
+judgeVerdictSchema.required = [];
+export function validateVerdict(verdict) {
+    return validateAcceptedJudgeDetails(verdict);
+}
+export function createJudgeRoleRuntime(pi, dependencies, hostActions) {
+    let soul;
+    let lifecycleRegistered = false;
+    return {
+        async activate() {
+            soul = (await dependencies.loadSoul()).trim();
+            if (soul.length === 0)
+                throw new Error("Judge soul is empty");
+            if (!lifecycleRegistered) {
+                lifecycleRegistered = true;
+                pi.registerTool({
+                    name: JUDGE_OUTPUT_TOOL_NAME,
+                    label: "大理寺输出",
+                    description: "提交大理寺终局判词；受理前经审刑院审计。",
+                    promptSnippet: "提交大理寺终局判词",
+                    parameters: judgeVerdictSchema,
+                    async execute(toolCallId, parameters, signal, _onUpdate, ctx) {
+                        if (soul === undefined)
+                            throw new Error("大理寺职分未装载");
+                        const verdict = validateVerdict(parameters);
+                        // Candidate verdict is already on the parent session books as this
+                        // tool-call leaf (first-record-then-audit; run 019fea05 L61/L62).
+                        // Gatekeeper runs after the draft is booked and before existing auditor.
+                        await pi.requireGatekeeperPass({
+                            context: ctx,
+                            subject: { kind: "judge_draft" },
+                            ...(signal === undefined ? {} : { signal }),
+                            hostActions,
+                            toolCallId,
+                        });
+                        let audit;
+                        try {
+                            audit = await dependencies.auditSoulCompliance(signal === undefined
+                                ? { context: ctx }
+                                : { context: ctx, signal });
+                        }
+                        catch (error) {
+                            hostActions.failInfrastructure(error, ctx, toolCallId);
+                        }
+                        const acceptedDetails = verdict;
+                        return disposeComplianceDecision(audit, {
+                            pass: (usage) => ({
+                                content: [{ type: "text", text: JUDGE_ACCEPTED_TEXT }],
+                                details: acceptedDetails,
+                                terminate: true,
+                                ...(usage === undefined ? {} : { usage }),
+                            }),
+                            noReceipt: (auditNoReceipt, usageProjection) => ({
+                                content: [{ type: "text", text: JUDGE_ACCEPTED_AUDIT_NO_RECEIPT_TEXT }],
+                                details: { ...acceptedDetails, auditNoReceipt },
+                                terminate: true,
+                                ...usageProjection,
+                            }),
+                            // #757: parent stands with auditor raw reply — no unreadable judgment.
+                            received: (auditReceived, usageProjection) => ({
+                                content: [{ type: "text", text: JUDGE_ACCEPTED_TEXT }],
+                                details: { ...acceptedDetails, audit: auditReceived.reply },
+                                terminate: true,
+                                ...usageProjection,
+                            }),
+                            bounce: (violations) => {
+                                throw new Error(`大理寺回执违 soul：${violations.join("; ")}`);
+                            },
+                            escalate: (result) => result,
+                        }, 
+                        // #380: escalate deliveredOutput must carry the same mechanical projection.
+                        acceptedDetails);
+                    },
+                });
+                pi.on("before_agent_start", (event) => {
+                    if (soul === undefined)
+                        throw new Error("大理寺职分未装载");
+                    return {
+                        systemPrompt: `${event.systemPrompt}\n\n<judge_soul>\n${soul}\n</judge_soul>`,
+                    };
+                });
+            }
+        },
+    };
+}

package/dist/merger-role.js

@@ -0,0 +1,66 @@
+import { MERGER_ACCEPTED_TEXT, MERGER_OUTPUT_TOOL_NAME, mergerOutputSchema, validateMergerInput, validateMergerOutput } from "./merger-contracts.js";
+import { exactUtf8 } from "./exact-utf8.js";
+import { isFullGitObjectId } from "./git-object-id.js";
+export { MERGER_OUTPUT_TOOL_NAME };
+export const MERGER_INPUT_FLAG = { name: "ak-merger-input", definition: { description: "Path to an immutable digest-bound Merger v1 input JSON file", type: "string" } };
+function same(a, b) { return a.length === b.length && a.every((value, i) => value === b[i]); }
+function materialText(input, key) { return exactUtf8(Buffer.from(input.materials[key].bytesBase64, "base64"), `Merger ${key}`); }
+export function createMergerRoleRuntime(pi, dependencies, host) {
+    let activation;
+    let registered = false;
+    let accepted = false;
+    pi.registerFlag(MERGER_INPUT_FLAG.name, MERGER_INPUT_FLAG.definition);
+    return { async activate() {
+            const path = pi.getFlag(MERGER_INPUT_FLAG.name);
+            if (typeof path !== "string" || path.trim().length === 0)
+                throw new Error("Merger requires --ak-merger-input");
+            const soul = (await dependencies.loadSoul()).trim();
+            if (!soul)
+                throw new Error("Merger soul is empty");
+            const input = validateMergerInput(await dependencies.loadInput(path));
+            const state = await dependencies.gitState.activeMerge();
+            if (state.targetObjectId !== input.targetObjectId || state.sourceObjectId !== input.sourceObjectId || !same(state.unmergedPaths, input.expectedConflictPaths) || state.unmergedPaths.length === 0 || !isFullGitObjectId(state.automaticMergeTreeId) || state.automaticMergeTreeId.length !== input.targetObjectId.length)
+                throw new Error("Merger activation rejected repository parent, merge, automatic-result, or complete conflict-set drift");
+            activation = { soul, input, automaticMergeTreeId: state.automaticMergeTreeId };
+            accepted = false;
+            if (!registered) {
+                registered = true;
+                pi.registerTool({ name: MERGER_OUTPUT_TOOL_NAME, label: "合并输出", description: "提交合并结果；输出分支为 completed 与 escalate；基础设施及 Git 失败由 abort 通道承接。", promptSnippet: "提交合并结果", parameters: mergerOutputSchema,
+                    async execute(id, params, _signal, _update, ctx) {
+                        if (!activation)
+                            throw new Error("校书郎未激活");
+                        if (accepted)
+                            throw new Error("合并回执已受理");
+                        let output;
+                        try {
+                            output = validateMergerOutput(params, activation.input.attemptId);
+                        }
+                        catch (error) {
+                            host.failInfrastructure(error, ctx, id);
+                        }
+                        if (output.status === "completed") {
+                            let state;
+                            try {
+                                state = await dependencies.gitState.completedMerge(output.mergeCommitId, activation.automaticMergeTreeId);
+                            }
+                            catch (error) {
+                                host.failInfrastructure(error, ctx, id);
+                            }
+                            const scope = new Set(activation.input.resolutionScope);
+                            if (state.mergeCommitId !== output.mergeCommitId || !same(state.parentObjectIds, [activation.input.targetObjectId, activation.input.sourceObjectId]) || state.unmergedPaths.length !== 0 || !state.worktreeClean || state.resolutionChangedPaths.some(path => !scope.has(path)))
+                                host.failInfrastructure(new Error("Merger completed-state verification failed"), ctx, id);
+                        }
+                        accepted = true;
+                        const acceptedDetails = output;
+                        return { content: [{ type: "text", text: MERGER_ACCEPTED_TEXT }], details: acceptedDetails, terminate: true };
+                    } });
+                pi.on("before_agent_start", (event) => { if (!activation)
+                    throw new Error("校书郎未激活"); const admitted = { attemptId: activation.input.attemptId, targetObjectId: activation.input.targetObjectId, sourceObjectId: activation.input.sourceObjectId, task: materialText(activation.input, "task"), authority: materialText(activation.input, "authority"), targetIntent: materialText(activation.input, "targetIntent"), sourceIntent: materialText(activation.input, "sourceIntent"), expectedConflictPaths: activation.input.expectedConflictPaths, resolutionScope: activation.input.resolutionScope, authorizedChecks: activation.input.authorizedChecks }; return { systemPrompt: `${event.systemPrompt}\n\n<merger_soul>\n${activation.soul}\n</merger_soul>\n\n<merger_assignment>\n${JSON.stringify(admitted)}\n</merger_assignment>` }; });
+            }
+            // Host-neutral AK output only (ADR 0018 fail-closed); no host-builtin name hard-require.
+            const all = pi.getAllTools().map(tool => tool.name);
+            if (all.filter(item => item === MERGER_OUTPUT_TOOL_NAME).length !== 1) {
+                throw new Error(`Merger required tool collision or missing: ${MERGER_OUTPUT_TOOL_NAME}`);
+            }
+        } };
+}

package/dist/navigator-public-session.js

@@ -98,11 +98,7 @@ function createNativeNavigatorSessionFactory() {
               return;
             }
             if (outcome.kind !== "accepted") {
-              providerFailure = { source: "session", cause: "session" };
-              throw navigatorUnavailableError(
-                "session",
-                new Error("Navigator public summon returned unusable terminal")
-              );
+              return;
             }
             const candidates = outcome.decisiveFacts.candidates;
             if (!Array.isArray(candidates)) {

package/dist/navigator-role.js

@@ -0,0 +1,12 @@
+import { NAVIGATOR_OUTPUT_TOOL_NAME, navigatorOutputSchema } from "./package-contracts/navigator-output.js";
+/**
+ * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
+ * Candidates share the route-advice shape the attendance prepare tool owns.
+ */
+export const NAVIGATOR_TOOL_SPEC = {
+    name: NAVIGATOR_OUTPUT_TOOL_NAME,
+    label: "游奕使建议",
+    description: "游奕使终局回执：排好序的下一步角色路线建议。",
+    promptSnippet: "游奕使建议",
+    parameters: navigatorOutputSchema,
+};

package/dist/notary-contracts.js

@@ -74,30 +74,12 @@ function validateRecordedNotaryOutput(value) {
   }
   return projected;
 }
-function notaryDecisiveFacts(output) {
-  const status = String(output.status);
-  const facts = { status, officer: "notary" };
-  if (status === "pass" || status === "bounce") {
-    const findings = output.findings;
-    facts.findingsCount = Array.isArray(findings) ? findings.length : 0;
-    facts.findings = Array.isArray(findings) ? findings : [];
-  }
-  if (status === "bounce") {
-    facts.disposition = "rewrite";
-  }
-  if (status === "escalate") {
-    const reason = output.reason;
-    if (reason !== void 0) facts.reason = reason;
-  }
-  return facts;
-}
 export {
   NOTARY_ACCEPTED_TEXT,
   NOTARY_FIXED_KICKOFF,
   NOTARY_OUTPUT_TOOL_NAME,
   NOTARY_SOURCE_RUN_FLAG,
   NOTARY_TICKET_FLAG,
-  notaryDecisiveFacts,
   notaryOutputSchema,
   projectLawfulNotaryOutput,
   retainNotarySubmission,

package/dist/notary-role.js

@@ -0,0 +1,137 @@
+/**
+ * Public Notary role runtime — direct officer seat (not through Gatekeeper province).
+ * Caller supplies only a source-run locator; Notary self-fetches authoritative materials.
+ * Ticket flag register/read/session bind is envelope-owned (ADR 0018 / #582).
+ * This module keeps evidence assembly + projection only.
+ */
+import { NOTARY_ACCEPTED_TEXT, NOTARY_OUTPUT_TOOL_NAME, NOTARY_SOURCE_RUN_FLAG, NOTARY_TICKET_FLAG, notaryOutputSchema, projectLawfulNotaryOutput, retainNotarySubmission, } from "./notary-contracts.js";
+export { NOTARY_ACCEPTED_TEXT, NOTARY_OUTPUT_TOOL_NAME, NOTARY_SOURCE_RUN_FLAG, NOTARY_TICKET_FLAG, };
+/** Optional ticket flag: absent/blank = unbound; non-empty invalid = honest fail. */
+export function readNotaryTicketFlag(flag) {
+    if (flag === undefined)
+        return undefined;
+    if (typeof flag !== "string") {
+        throw new Error("Notary ak-notary-ticket-number is present but not a safe positive integer string");
+    }
+    if (flag.trim() === "")
+        return undefined;
+    const n = Number(flag);
+    if (!Number.isSafeInteger(n) || n < 1) {
+        throw new Error("Notary ak-notary-ticket-number is present but not a safe positive integer string");
+    }
+    return n;
+}
+/**
+ * Typed session bound (locator + optional ticket).
+ * Sole production projection for agent-start material + session custom entry.
+ */
+export function projectNotarySessionBound(input) {
+    return {
+        sourceRun: input.sourceRun,
+        ...(input.ticketNumber === undefined ? {} : { ticketNumber: input.ticketNumber }),
+    };
+}
+/**
+ * Session custom-entry type for typed notary bound (written by shared envelope).
+ * Role module only projects; lifecycle write is envelope-owned (ADR 0018).
+ */
+export const NOTARY_SESSION_BOUND_ENTRY = "notary-session-bound";
+/**
+ * Project notary bound from host flags (envelope consumption seam).
+ * undefined when source-run flag absent/blank.
+ * Ticket invalid → throws (honest fail; envelope owns the read).
+ */
+export function projectNotaryBoundFromFlags(getFlag) {
+    const path = getFlag(NOTARY_SOURCE_RUN_FLAG.name);
+    if (typeof path !== "string" || path.trim() === "")
+        return undefined;
+    const ticketNumber = readNotaryTicketFlag(getFlag(NOTARY_TICKET_FLAG.name));
+    return {
+        sourceRunPath: path,
+        ...(ticketNumber === undefined ? {} : { ticketNumber }),
+    };
+}
+/** Assemble systemPrompt body from base + soul only (NO embedded bound JSON).
+ * The typed session bound travels separately as `readingMaterial`; adapters fold
+ * it into the provider-visible prompt at the send boundary. */
+export function assembleNotaryAgentStartPrompt(input) {
+    return `${input.baseSystemPrompt}\n\n<notary_soul>\n${input.soul}\n</notary_soul>`;
+}
+export function createNotaryRoleRuntime(pi, dependencies, host) {
+    let activation;
+    let registered = false;
+    // Baseline source-run flag registration (pre-#582). Ticket flag is envelope-owned.
+    pi.registerFlag(NOTARY_SOURCE_RUN_FLAG.name, NOTARY_SOURCE_RUN_FLAG.definition);
+    return {
+        /**
+         * @param admitted Optional ticket from envelope flag decode (ADR 0018).
+         * Role module never getFlag's the ticket — envelope owns that read.
+         */
+        async activate(admitted) {
+            const path = pi.getFlag(NOTARY_SOURCE_RUN_FLAG.name);
+            if (typeof path !== "string" || path.trim() === "") {
+                throw new Error("Notary requires --ak-notary-source-run");
+            }
+            const soul = (await dependencies.loadSoul()).trim();
+            if (soul.length === 0)
+                throw new Error("Notary soul is empty");
+            const sourceRun = await dependencies.loadSourceRunLocator(path);
+            activation = {
+                soul,
+                sourceRun,
+                ...(admitted?.ticketNumber === undefined
+                    ? {}
+                    : { ticketNumber: admitted.ticketNumber }),
+            };
+            if (!registered) {
+                registered = true;
+                pi.registerTool({
+                    name: NOTARY_OUTPUT_TOOL_NAME,
+                    label: "符宝郎输出",
+                    description: "提交引文保真与票面对齐的 typed pass/bounce/escalate 决议。",
+                    promptSnippet: "提交符宝郎决议",
+                    parameters: notaryOutputSchema,
+                    async execute(toolCallId, parameters, _signal, _onUpdate, ctx) {
+                        if (activation === undefined) {
+                            throw new Error("符宝郎未激活");
+                        }
+                        // Unique submission + terminate only. Shape is not an admission gate
+                        // (第 0 条 / ADR 0055): lawful pass/bounce/escalate projected; else params as-is.
+                        // #541 infra declaration + sole-final barrier are ledger-owned (#575).
+                        const lawful = projectLawfulNotaryOutput(parameters);
+                        const details = lawful ?? retainNotarySubmission(parameters);
+                        return {
+                            content: [{ type: "text", text: NOTARY_ACCEPTED_TEXT }],
+                            details,
+                            terminate: true,
+                        };
+                    },
+                });
+                // Evidence assembly only (ADR 0018): soul + bound projection.
+                // Ticket value is envelope-admitted at activate — not re-read from flags here.
+                pi.on("before_agent_start", (event) => {
+                    if (activation === undefined) {
+                        throw new Error("符宝郎未激活");
+                    }
+                    return {
+                        systemPrompt: assembleNotaryAgentStartPrompt({
+                            baseSystemPrompt: event.systemPrompt,
+                            soul: activation.soul,
+                        }),
+                        readingMaterial: projectNotarySessionBound({
+                            sourceRun: activation.sourceRun,
+                            ...(activation.ticketNumber === undefined
+                                ? {}
+                                : { ticketNumber: activation.ticketNumber }),
+                        }),
+                    };
+                });
+            }
+            // Evidence role: keep Pi default tools + notary output (ADR 0064 unrestricted).
+            const all = pi.getAllTools().map((tool) => tool.name);
+            if (all.filter((name) => name === NOTARY_OUTPUT_TOOL_NAME).length !== 1) {
+                throw new Error(`Notary required tool collision or missing: ${NOTARY_OUTPUT_TOOL_NAME}`);
+            }
+        },
+    };
+}