@akagilnc/pi-workflow-roles 0.1.3648 → 0.1.3652

package/dist/role-runtime.js

@@ -0,0 +1,1394 @@
+import { writeSync } from "node:fs";
+import { ExplicitInternalActivationError, } from "./host-contracts.js";
+import { recordReviewerDispatchRejectionSync } from "./public-cli/reviewer-dispatch-rejection.js";
+import { Value } from "typebox/value";
+import { sitianReport } from "./sitian-facade.js";
+import { createSubmissionLedgerHost } from "./submission-ledger.js";
+import { createCollectorLedger } from "./collector-ledger.js";
+import { activationTraceRecordSchema, namedActivationCause } from "./activation-trace.js";
+import { resolveActivationLedgerHomeForPath } from "./activation-ledger-topology.js";
+import { appendAcceptedActivationToBook, buildAcceptedActivationFact, correlationIdentityFromEnv, durableSessionPointer, resolveActivationLedgerHome, resolveBookKeyFromGit, } from "./activation-ledger.js";
+import { writeStderrJsonlRecord } from "./stderr-jsonl.js";
+import { createToolExecutionObservationFace, systemToolExecutionObservationMonoNow, writeToolExecutionObservationRecord, } from "./tool-execution-observation.js";
+import { ENGINE_DETOUR_TOOL_NAME } from "./engine-detour.js";
+import { registerEngineDetourTool } from "./engine-detour-tool.js";
+import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT } from "./receipt-delivery-policy.js";
+import { COLLECTOR_OBSERVE_TOOL, COLLECTOR_OUTPUT_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, createCollectorRoleRuntime, } from "./collector-role.js";
+import { createDoctorRoleRuntime } from "./doctor-role.js";
+import { createNotaryRoleRuntime, NOTARY_SESSION_BOUND_ENTRY, projectNotaryBoundFromFlags, readNotaryTicketFlag, } from "./notary-role.js";
+import { NOTARY_TICKET_FLAG } from "./notary-contracts.js";
+import { COUNTERSIGN_TOOL_SPEC, } from "./countersign-role.js";
+import { COUNTERSIGN_ACCEPTED_TEXT } from "./countersign-contracts.js";
+import { GLEANER_LEFT_TOOL_SPEC, } from "./gleaner-left-role.js";
+import { GLEANER_LEFT_ACCEPTED_TEXT, GLEANER_LEFT_BASE_FLAG } from "./gleaner-left-contracts.js";
+import { INSPECTOR_TOOL_SPEC, } from "./inspector-role.js";
+import { INSPECTOR_ACCEPTED_TEXT } from "./inspector-contracts.js";
+import { DIARIST_TOOL_SPEC, } from "./diarist-role.js";
+import { DIARIST_ACCEPTED_TEXT, DIARIST_SOURCES_FLAG, projectDiaristSelections, } from "./diarist-contracts.js";
+import { commitDiaristSelections, loadDiaristSourceCatalog, } from "./diarist.js";
+import { GATEKEEPER_TOOL_SPEC, } from "./gatekeeper-role.js";
+import { NAVIGATOR_TOOL_SPEC, } from "./navigator-role.js";
+import { AUDITOR_TOOL_SPEC, } from "./auditor-role.js";
+import { AUDITOR_ACCEPTED_TEXT } from "./package-contracts/auditor-output.js";
+import { GATEKEEPER_ACCEPTED_TEXT } from "./package-contracts/gatekeeper-output.js";
+import { NAVIGATOR_ACCEPTED_TEXT } from "./package-contracts/navigator-output.js";
+import { decorateSettlementWithNavigation, formatNavigatorReport, NAVIGATOR_EVENT_TYPE, navigatorSubjectKey, navigatorUnavailableError, subjectPath } from "./navigator-attendance.js";
+import { buildNavigatorInfrastructureFailureFact, classifyPackagedRoleTerminalResult, extractInfrastructureFailureEvidence, NAVIGATOR_INVOCATION_ENTRY, resolveLifecycleInvocationPrincipal, } from "./navigator-invocation-identity.js";
+import { recordTypedProviderHttpStatus } from "./typed-provider-http.js";
+import { NAVIGATOR_POST_ROLE_GRACE_MS, raceNavigatorGrace } from "./public-cli/settlement.js";
+import { PACKAGED_ROLE_REGISTRY, packagedRoleMetadata, packagedRoleOutputTool, packagedRolePhaseFlag } from "./packaged-role-registry.js";
+import { isAuditEscalationProjection } from "./audit-escalation.js";
+import { createJudgeRoleRuntime, } from "./judge-role.js";
+import { createReviewerRoleRuntime, } from "./reviewer-role.js";
+import {} from "./reviewer-construction.js";
+/**
+ * Private transport flag names/definitions for Reviewer admitted inputs.
+ * Shared activation envelope owns registration and decoding (ADR 0018).
+ */
+const REVIEWER_TRANSPORT_FLAGS = Object.freeze([
+    Object.freeze({
+        name: "ak-review-base",
+        definition: Object.freeze({
+            description: "Fixed base revision for the pinned review target",
+            type: "string",
+        }),
+    }),
+    Object.freeze({
+        name: "ak-review-scope-keys",
+        definition: Object.freeze({
+            description: "Optional comma-separated exact class keys limiting Reviewer scope",
+            type: "string",
+        }),
+    }),
+    Object.freeze({
+        name: "ak-review-authority-refs",
+        definition: Object.freeze({
+            description: "JSON array of durable authority references for Spec-axis material only",
+            type: "string",
+        }),
+    }),
+    Object.freeze({
+        name: "ak-review-ticket-number",
+        definition: Object.freeze({
+            description: "Typed ticketNumber for Spec self-fetch primary path",
+            type: "string",
+        }),
+    }),
+]);
+/** Notary private transport: optional court-diary ticket (ADR 0018 / 0075 — envelope-owned). */
+const NOTARY_TRANSPORT_FLAGS = Object.freeze([
+    Object.freeze({
+        name: NOTARY_TICKET_FLAG.name,
+        definition: NOTARY_TICKET_FLAG.definition,
+    }),
+]);
+/** Gleaner-left private transport: comparison-base revision (ADR 0018 / #502). */
+const GLEANER_LEFT_TRANSPORT_FLAGS = Object.freeze([
+    Object.freeze({
+        name: GLEANER_LEFT_BASE_FLAG.name,
+        definition: GLEANER_LEFT_BASE_FLAG.definition,
+    }),
+]);
+/** Diarist private transport: frozen source catalog path (ADR 0018 / #708). */
+const DIARIST_TRANSPORT_FLAGS = Object.freeze([
+    Object.freeze({
+        name: DIARIST_SOURCES_FLAG.name,
+        definition: DIARIST_SOURCES_FLAG.definition,
+    }),
+]);
+/**
+ * Decode private transport flags into frozen admitted inputs.
+ * Envelope-owned; necessary JSON decode only (public --authority-ref owns grammar).
+ */
+function decodeReviewerAdmittedInputs(getFlag) {
+    let reviewScopeKeys;
+    const rawScopeKeys = getFlag("ak-review-scope-keys");
+    if (rawScopeKeys !== undefined) {
+        if (typeof rawScopeKeys !== "string" || rawScopeKeys.length === 0) {
+            throw new Error("Reviewer scope keys must be a nonempty comma-separated string");
+        }
+        const parsed = rawScopeKeys.split(",");
+        if (parsed.some((key) => key.trim().length === 0) || new Set(parsed).size !== parsed.length) {
+            throw new Error("Reviewer scope keys contain a blank or exact duplicate key");
+        }
+        reviewScopeKeys = Object.freeze(parsed);
+    }
+    let authorityRefs;
+    const rawAuthorityRefs = getFlag("ak-review-authority-refs");
+    if (rawAuthorityRefs !== undefined) {
+        if (typeof rawAuthorityRefs !== "string") {
+            throw new Error("Reviewer authority refs transport error: flag value must be a string");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(rawAuthorityRefs);
+        }
+        catch (error) {
+            throw new Error(`Reviewer authority refs transport error: JSON decode failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!Array.isArray(parsed) || parsed.some((ref) => typeof ref !== "string")) {
+            throw new Error("Reviewer authority refs transport error: expected a JSON array of strings");
+        }
+        authorityRefs = Object.freeze(parsed);
+    }
+    let ticketNumber;
+    const rawTicketNumber = getFlag("ak-review-ticket-number");
+    // Shape-invalid flag values do not abort: omit typed candidate; branch→commit→degrade continues.
+    if (typeof rawTicketNumber === "string" && /^[1-9]\d*$/.test(rawTicketNumber)) {
+        ticketNumber = Number(rawTicketNumber);
+    }
+    const baseRevision = getFlag("ak-review-base");
+    if (typeof baseRevision !== "string" || !baseRevision.trim()) {
+        throw new Error("Reviewer role requires --ak-review-base");
+    }
+    return Object.freeze({
+        baseRevision,
+        ...(reviewScopeKeys === undefined ? {} : { reviewScopeKeys }),
+        ...(authorityRefs === undefined ? {} : { authorityRefs }),
+        ...(ticketNumber === undefined ? {} : { ticketNumber }),
+    });
+}
+/**
+ * Parent system-prompt assembly for the shared activation envelope.
+ * Verification cadence lives in soul/quality-law only (ADR 0073: no machine copy).
+ */
+function assembleReviewerParentSystemPrompt(input) {
+    const specDispositionNote = input.specDisposition === "skipped-missing"
+        ? [
+            "",
+            "<reviewer_spec_disposition>",
+            "权威 Spec 不存在；未启动 Spec 取证腿。",
+            "</reviewer_spec_disposition>",
+        ]
+        : [];
+    return [
+        input.baseSystemPrompt,
+        "",
+        "<reviewer_soul>",
+        input.soul,
+        "</reviewer_soul>",
+        ...specDispositionNote,
+    ].join("\n");
+}
+import { CODER_OUTPUT_TOOL_NAME, createCoderRoleRuntime, createFixerRoleRuntime, FIXER_FLAG_DEFINITIONS, FIXER_OUTPUT_TOOL_NAME, FIXER_PHASES, } from "./worker-role.js";
+import { JUDGE_OUTPUT_TOOL_NAME } from "./package-contracts/judge-output.js";
+import { REVIEWER_OUTPUT_TOOL_NAME } from "./package-contracts/reviewer-output.js";
+import { DOCTOR_OUTPUT_TOOL_NAME } from "./doctor-contracts.js";
+import { MERGER_OUTPUT_TOOL_NAME } from "./merger-contracts.js";
+import { createMergerRoleRuntime } from "./merger-role.js";
+export { buildNavigatorInfrastructureFailureFact, classifyPackagedRoleTerminalResult, extractInfrastructureFailureEvidence, hasNavigatorInfrastructureFailureBase, isAcceptedPackagedRoleTerminalResult, isDurablePackagedRoleTerminalResult, isNavigatorInfrastructureFailureFact, NAVIGATOR_INFRASTRUCTURE_FAILURE_EVIDENCE_KEYS, NAVIGATOR_INFRASTRUCTURE_FAILURE_KIND, } from "./navigator-invocation-identity.js";
+export { activationTraceRecordSchema, namedActivationCause } from "./activation-trace.js";
+export { ACCEPTED_ACTIVATION_EVENT, ACCEPTED_ACTIVATION_FACT_KEYS, ActivationGitRepositoryRequiredError, ActivationLedgerError, ActivationSessionFileMissingError, activationBookDirectory, activationWaitingLedgerPath, appendAcceptedActivationFact, appendAcceptedActivationToBook, buildAcceptedActivationFact, correlationIdentityFromEnv, durableSessionPointer, resolveActivationLedgerHome, resolveBookKeyFromGit, serializeAcceptedActivationFact, } from "./activation-ledger.js";
+export { DISPATCH_STUB_EVENT, buildDispatchStubFact, reconcileInvocation, } from "./activation-reconciliation.js";
+export { TOOL_EXECUTION_UPDATE_HEARTBEAT, TOOL_EXECUTION_UPDATE_THROTTLE_MS, createToolExecutionObservationFace, isProducingToolUpdate, systemToolExecutionObservationMonoNow, toolExecutionObservationRecordSchema, validateToolExecutionObservationRecord, writeToolExecutionObservationRecord, } from "./tool-execution-observation.js";
+export { NOTARY_OUTPUT_TOOL, INSPECTOR_OUTPUT_TOOL, GatekeeperDecisionError, createGatekeeperOutputTool, runGatekeeper, } from "./gatekeeper-role.js";
+export { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME, } from "./doctor-role.js";
+export { validateDoctorSubmissionShape, validateDoctorOutput, DoctorEvidenceStore } from "./doctor-contracts.js";
+export { loadDoctorCase } from "./doctor-evidence.js";
+export { JUDGE_OUTPUT_TOOL_NAME, } from "./judge-role.js";
+export { ENGINE_DETOUR_TOOL_NAME, AK_ROLE_ENGINE_ENV } from "./engine-detour.js";
+export { AGENT_TOOL_NAME, REVIEWER_OUTPUT_TOOL_NAME, } from "./reviewer-role.js";
+export { CODER_OUTPUT_TOOL_NAME, CODER_SKILL_EXPANSION_EVIDENCE_MISSING_CODE, CoderSkillExpansionEvidenceMissingError, FIXER_FLAG_DEFINITIONS, FIXER_OUTPUT_TOOL_NAME, FIXER_PHASES, } from "./worker-role.js";
+export { fixerOutputSchema, validateFixerOutput, validateFixerOutputForPacket } from "./package-contracts/fixer-output.js";
+export { fixerPrerequisiteSchema, fixerPrerequisitesSchema, parseFixerPrerequisites, validateFixerPrerequisites } from "./package-contracts/fixer-packet.js";
+export { AUDIT_ESCALATION_KIND, buildAuditEscalationResult, disposeComplianceDecision, isAuditEscalationResult, projectAuditEscalation } from "./audit-escalation.js";
+export { AUDITOR_SOUL_ROLES, AK_ROLE_AUDITOR_SUBJECT_ENV, loadAuditorSoul, loadAuditorSoulFromSubjectInput, resolveAuditorSubject, } from "./auditor-soul.js";
+export { JUDGE_AUDIT_TOOL_NAME, SOUL_AUDIT_TOOL_NAME, createPiJudgeAuditor } from "./judge-auditor.js";
+export { DOCTOR_AUDIT_TOOL_NAME, createPiDoctorAuditor } from "./doctor-auditor.js";
+export { COLLECTOR_OBSERVE_TOOL, COLLECTOR_OUTPUT_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, } from "./collector-role.js";
+export * from "./navigator-attendance.js";
+export { MERGER_INPUT_FLAG, createMergerRoleRuntime } from "./merger-role.js";
+export { MERGER_OUTPUT_TOOL_NAME, mergerInputSchema, mergerOutputSchema, validateMergerInput, validateMergerOutput } from "./merger-contracts.js";
+export { createProductionMergerGitState } from "./merger-git-state.js";
+function activationStage(role, runtime) {
+    switch (role) {
+        case "judge": return { id: "load-and-install", run: async () => runtime.judge.activate() };
+        case "fixer": return { id: "load-and-install", run: async () => runtime.fixer.activate() };
+        case "coder": return { id: "load-and-install", run: async () => runtime.coder.activate(runtime.context) };
+        case "reviewer": return { id: "load-install-and-dispatch", run: async () => {
+                // Envelope owns flag decode inside the activation stage (trace + fail-closed path).
+                const admitted = runtime.decodeReviewerAdmitted();
+                const activation = await runtime.reviewer.activate(runtime.context, admitted);
+                runtime.bindReviewerParent(activation);
+                const result = await activation.dispatcher.dispatch(activation.fixedBaseRevision, { context: runtime.context });
+                if (result.status !== "accepted") {
+                    const rejection = new ExplicitInternalActivationError(`Fixed Reviewer dispatch was not accepted: ${result.status}: ${result.diagnostic}`, {
+                        knownCause: "activation",
+                        name: "ReviewerDispatchRejectionError",
+                    });
+                    // Pi stderr cannot carry the structured violations. Do not mask a durable
+                    // write failure: its infrastructure cause is truer than the unwritten page.
+                    const runDir = process.env.AK_ROLE_RUN_DIR;
+                    if (typeof runDir === "string" && runDir.trim() !== "") {
+                        recordReviewerDispatchRejectionSync(runDir, {
+                            diagnostic: rejection.message,
+                            violations: result.violations,
+                        });
+                    }
+                    throw rejection;
+                }
+            } };
+        case "collector": return { id: "load-and-install", run: async () => runtime.collector.activate(runtime.context, runtime.event) };
+        case "doctor": return { id: "load-and-install", run: async () => runtime.doctor.activate() };
+        case "notary": return {
+            id: "load-and-install",
+            run: async () => {
+                // Envelope owns ticket flag read (ADR 0018); role receives admitted value only.
+                await runtime.notary.activate(runtime.decodeNotaryAdmitted());
+            },
+        };
+        case "countersign": return { id: "load-and-install", run: async () => runtime.countersign.activate() };
+        case "gleaner-left": return { id: "load-and-install", run: async () => runtime.gleanerLeft.activate() };
+        case "inspector": return { id: "load-and-install", run: async () => runtime.inspector.activate() };
+        case "gatekeeper": return { id: "load-and-install", run: async () => runtime.gatekeeper.activate() };
+        case "navigator": return { id: "load-and-install", run: async () => runtime.navigator.activate() };
+        case "auditor": return { id: "load-and-install", run: async () => runtime.auditor.activate() };
+        case "diarist": return { id: "load-and-install", run: async () => runtime.diarist.activate() };
+        case "merger": return { id: "prepare-git-and-install", run: async () => runtime.merger() };
+    }
+}
+function validateActivationTraceRecord(record) {
+    if (!Value.Check(activationTraceRecordSchema, record)) {
+        throw new TypeError("Activation trace record does not match its closed contract");
+    }
+    return record;
+}
+async function emitActivationTrace(writeTrace, record) {
+    await writeTrace(validateActivationTraceRecord(record));
+}
+async function executeActivationStage(role, stage, infrastructure) {
+    try {
+        await stage.run();
+    }
+    catch (activationError) {
+        try {
+            await emitActivationTrace(infrastructure.writeTrace, {
+                role,
+                stageId: stage.id,
+                status: "failed",
+                timestamp: infrastructure.clock(),
+                cause: namedActivationCause(activationError),
+            });
+        }
+        catch (traceError) {
+            throw new AggregateError([activationError, traceError], `Activation stage ${stage.id} failed and its failure trace could not be emitted`);
+        }
+        throw activationError;
+    }
+}
+export function writeActivationTraceRecord(record, write = writeSync) {
+    writeStderrJsonlRecord(record, write);
+}
+export class ActivationBarrierError extends Error {
+    code = "AK_ACTIVATION_NOT_ADMITTED";
+    constructor(role) {
+        super(`Workflow role ${String(role)} activation did not complete`);
+        this.name = "ActivationBarrierError";
+    }
+}
+export const WORKFLOW_ROLES = PACKAGED_ROLE_REGISTRY.map(({ role }) => role);
+export const ROLE_FLAG = {
+    name: "ak-role",
+    definition: {
+        description: `Activate a packaged workflow role: ${WORKFLOW_ROLES.slice(0, -1).join(", ")}, or ${WORKFLOW_ROLES.at(-1)}`,
+        type: "string",
+    },
+};
+/** Host-neutral in-process role help for Navigator prepare (Pi and Grok share this). */
+export function formatNavigatorRoleHelp(role) {
+    const metadata = packagedRoleMetadata(role);
+    const lines = [
+        `Usage: ak-role ${role}`,
+        ROLE_FLAG.definition.description,
+    ];
+    if (metadata?.inputFlag !== undefined) {
+        lines.push(`  --${metadata.inputFlag} <value>    ${role} input material`);
+    }
+    if (metadata?.phaseFlag !== undefined) {
+        lines.push(`  --${metadata.phaseFlag} <value>    ${role} phase: ${metadata.phases.filter((p) => p !== null).join(" | ")}`);
+    }
+    lines.push(`Public next-command form: ak-role ${role}`);
+    return lines.join("\n");
+}
+function abortContext(ctx) {
+    ctx.abort();
+}
+function failInfrastructure(error, ctx) {
+    abortContext(ctx);
+    if (ctx.mode === "print" || ctx.mode === "json")
+        process.exitCode = 1;
+    throw error;
+}
+function buildPendingInfrastructureFailure(error) {
+    return {
+        details: {
+            ...buildNavigatorInfrastructureFailureFact(),
+            ...extractInfrastructureFailureEvidence(error),
+        },
+    };
+}
+function navigatorPhase(roleHost, role) {
+    const metadata = packagedRoleMetadata(role);
+    if (metadata === undefined || metadata.phases[0] === null)
+        return null;
+    const phaseFlag = packagedRolePhaseFlag(role);
+    const requested = phaseFlag === undefined ? undefined : roleHost.getFlag(phaseFlag);
+    return requested === "apply" ? "apply" : "plan";
+}
+function navigatorOutputTool(role) {
+    return packagedRoleOutputTool(role);
+}
+export function publicNavigatorSettlement(role, phase, event) {
+    // One shared classifier owns terminal discriminant (lifecycle + settlement + extractors).
+    if (event.toolName !== navigatorOutputTool(role))
+        return undefined;
+    const classification = classifyPackagedRoleTerminalResult(event);
+    if (classification.kind === "nonterminal")
+        return undefined;
+    if (classification.kind === "infrastructure") {
+        return { kind: "role_infrastructure_failure", role, phase };
+    }
+    // accepted/human — project role/phase status; classifier already rejected infra/contradiction.
+    const details = typeof event.details === "object" && event.details !== null && !Array.isArray(event.details)
+        ? event.details
+        : {};
+    // Live Navigator consumes only the audit-owned projection; persisted/replayed
+    // records are re-authenticated by settlement against retained audit evidence.
+    if (isAuditEscalationProjection(event.details)) {
+        return { kind: "human_decision", role, phase, status: "audit_escalation" };
+    }
+    const status = typeof details.status === "string"
+        ? details.status
+        : typeof details.judgeStatus === "string" ? details.judgeStatus
+            : typeof details.countersignStatus === "string" ? details.countersignStatus : undefined;
+    if (status !== undefined && status === "escalate") {
+        return { kind: "human_decision", role, phase, status };
+    }
+    return { kind: "accepted", role, phase, ...(status === undefined ? {} : { status }) };
+}
+export async function projectClosedSubmissionLifecycle(projection, context, phase, recordAccepted, settle) {
+    recordAccepted();
+    const closure = {
+        toolName: navigatorOutputTool(projection.role),
+        isError: false,
+        details: projection.decisiveFacts,
+    };
+    context.sessionManager.appendCustomEntry?.("ak-role-submission-closure", closure);
+    await settle(publicNavigatorSettlement(projection.role, phase, closure));
+}
+/**
+ * Shared registration envelope for filed officers (ADR 0018 / #572):
+ * activate, tool register, before_agent_start prompt, inventory check.
+ * Role module keeps label/soul/spec shape only; sole-final barrier is ledger-owned.
+ * Optional beforeAccept is the sole extension seam (e.g. countersign Notary gate).
+ */
+function createFiledOfficerRuntime(roleHost, spec, dependencies) {
+    let soul;
+    let registered = false;
+    return {
+        async activate() {
+            const loaded = (await dependencies.loadSoul()).trim();
+            if (loaded.length === 0)
+                throw new Error(`${spec.role} soul is empty`);
+            soul = loaded;
+            if (!registered) {
+                registered = true;
+                roleHost.registerTool({
+                    name: spec.tool.name,
+                    label: spec.tool.label,
+                    description: spec.tool.description,
+                    promptSnippet: spec.tool.promptSnippet,
+                    parameters: spec.tool.parameters,
+                    async execute(toolCallId, parameters, signal, _onUpdate, ctx) {
+                        if (soul === undefined)
+                            throw new Error(`${spec.role} 职分未装载`);
+                        const projected = spec.beforeAccept === undefined
+                            ? undefined
+                            : await spec.beforeAccept({ toolCallId, parameters, signal, ctx });
+                        // Accept-as-is + terminate only. Shape is not an admission gate
+                        // (第 0 条 / ADR 0055); sole-final barrier is ledger-owned (#575).
+                        return {
+                            content: [{ type: "text", text: spec.acceptedText }],
+                            details: projected === undefined ? parameters : projected,
+                            terminate: true,
+                        };
+                    },
+                });
+                roleHost.on("before_agent_start", (event) => {
+                    if (soul === undefined)
+                        throw new Error(`${spec.role} 职分未装载`);
+                    const tail = `\n\n<${spec.soulTag}_soul>\n${soul}\n</${spec.soulTag}_soul>`;
+                    return { systemPrompt: `${event.systemPrompt}${tail}` };
+                });
+            }
+            const all = roleHost.getAllTools().map((tool) => tool.name);
+            if (all.filter((name) => name === spec.tool.name).length !== 1) {
+                throw new Error(`${spec.role} required tool collision or missing: ${spec.tool.name}`);
+            }
+        },
+    };
+}
+export function createGleanerLeftRoleRuntime(roleHost, dependencies) {
+    return createFiledOfficerRuntime(roleHost, {
+        role: "gleaner-left",
+        tool: GLEANER_LEFT_TOOL_SPEC,
+        acceptedText: GLEANER_LEFT_ACCEPTED_TEXT,
+        soulTag: "gleaner-left",
+    }, dependencies);
+}
+function decodeGleanerLeftBase(getFlag) {
+    const baseRevision = getFlag(GLEANER_LEFT_BASE_FLAG.name);
+    if (typeof baseRevision !== "string" || !baseRevision.trim()) {
+        throw new Error("Gleaner-left role requires --ak-gleaner-left-base");
+    }
+    return baseRevision;
+}
+export function createInspectorRoleRuntime(roleHost, dependencies) {
+    return createFiledOfficerRuntime(roleHost, {
+        role: "inspector",
+        tool: INSPECTOR_TOOL_SPEC,
+        acceptedText: INSPECTOR_ACCEPTED_TEXT,
+        soulTag: "inspector",
+    }, dependencies);
+}
+/** #639: direct Gatekeeper public seat on the shared filed-officer envelope. */
+export function createGatekeeperRoleRuntime(roleHost, dependencies) {
+    return createFiledOfficerRuntime(roleHost, {
+        role: "gatekeeper",
+        tool: GATEKEEPER_TOOL_SPEC,
+        acceptedText: GATEKEEPER_ACCEPTED_TEXT,
+        soulTag: "gatekeeper",
+    }, dependencies);
+}
+/** #639: direct Navigator public seat on the shared filed-officer envelope. */
+export function createNavigatorRoleRuntime(roleHost, dependencies) {
+    return createFiledOfficerRuntime(roleHost, {
+        role: "navigator",
+        tool: NAVIGATOR_TOOL_SPEC,
+        acceptedText: NAVIGATOR_ACCEPTED_TEXT,
+        soulTag: "navigator",
+    }, dependencies);
+}
+/** #675: public 审刑院 seat on the shared filed-officer envelope. */
+export function createAuditorRoleRuntime(roleHost, dependencies) {
+    const base = createFiledOfficerRuntime(roleHost, {
+        role: "auditor",
+        tool: AUDITOR_TOOL_SPEC,
+        acceptedText: AUDITOR_ACCEPTED_TEXT,
+        soulTag: "auditor",
+    }, dependencies);
+    return {
+        async activate() {
+            await base.activate();
+            // Same tools whether nested or direct (#675): dossier tool always registered.
+            // Source run: only the shared --source-run input face (never own-run fallback).
+            const { createAuditorDossierTool, AUDITOR_DOSSIER_TOOL_NAME } = await import("./auditor-dossier-tool.js");
+            const { AK_ROLE_AUDITOR_SOURCE_RUN_ENV } = await import("./auditor-soul.js");
+            const already = roleHost.getAllTools().some((tool) => tool.name === AUDITOR_DOSSIER_TOOL_NAME);
+            if (already)
+                return;
+            const sourceRun = typeof process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV] === "string"
+                && process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV].trim() !== ""
+                ? process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV].trim()
+                : undefined;
+            roleHost.registerTool(createAuditorDossierTool(sourceRun));
+        },
+    };
+}
+/**
+ * #708: 起居郎 public seat on the shared filed-officer envelope.
+ * Semantic collection happened in this role's own turn; the accept hook runs the
+ * mechanical band (verbatim reverse-verify → idempotent sitian append →
+ * watermark) and records the resulting sitian facts next to the receipt.
+ * Machine facts never come from model self-report (锚定宪法).
+ */
+export function createDiaristRoleRuntime(roleHost, dependencies, getSourcesFlag) {
+    // This turn's catalog, snapshotted at activate: the candidateIndexes the role
+    // saw and the rows accept commits are the same bytes. Accept never re-reads
+    // the file, so anything written to it mid-turn cannot become a diary entry.
+    let catalog;
+    const runtime = createFiledOfficerRuntime(roleHost, {
+        role: "diarist",
+        tool: DIARIST_TOOL_SPEC,
+        acceptedText: DIARIST_ACCEPTED_TEXT,
+        soulTag: "diarist",
+        beforeAccept: async ({ parameters }) => {
+            const submitted = parameters !== null && typeof parameters === "object" && !Array.isArray(parameters)
+                ? parameters
+                : undefined;
+            // True-unbound summons: no ticket, no catalog, no diary committed — so
+            // this turn produced no sitian facts. A self-reported `sitian` is not
+            // one (锚定宪法); drop it rather than let it ride into decisiveFacts.
+            // Carrying the field is not a reason to bounce the receipt (第 0 条).
+            if (catalog === undefined) {
+                if (submitted === undefined || !("sitian" in submitted))
+                    return undefined;
+                const stripped = { ...submitted };
+                delete stripped.sitian;
+                return stripped;
+            }
+            const facts = await commitDiaristSelections({
+                catalog,
+                selections: projectDiaristSelections(parameters),
+            });
+            return { ...(submitted ?? { receipt: parameters }), sitian: facts };
+        },
+    }, dependencies);
+    return {
+        async activate() {
+            catalog = loadFrozenDiaristCatalog(getSourcesFlag);
+            return runtime.activate();
+        },
+    };
+}
+/** Envelope-owned decode + one-shot load of the frozen catalog (ADR 0018). */
+function loadFrozenDiaristCatalog(getFlag) {
+    const raw = getFlag();
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== "string" || raw.trim() === "") {
+        throw new Error("Diarist source catalog flag must be a nonempty path");
+    }
+    return loadDiaristSourceCatalog(raw);
+}
+export function createCountersignRoleRuntime(roleHost, dependencies, hostActions) {
+    // Notary inner gate difference only — lifecycle stays on the shared envelope.
+    // Pointer-only summons: officer self-fetches from run dossier (#632 / ADR 0079).
+    const beforeAccept = hostActions !== undefined && roleHost.requireGatekeeperPass !== undefined
+        ? async ({ toolCallId, signal, ctx }) => {
+            await roleHost.requireGatekeeperPass({
+                context: ctx,
+                subject: { kind: "countersign_verdict" },
+                ...(signal === undefined ? {} : { signal }),
+                hostActions,
+                toolCallId,
+            });
+        }
+        : undefined;
+    return createFiledOfficerRuntime(roleHost, {
+        role: "countersign",
+        tool: COUNTERSIGN_TOOL_SPEC,
+        acceptedText: COUNTERSIGN_ACCEPTED_TEXT,
+        soulTag: "countersign",
+        ...(beforeAccept === undefined ? {} : { beforeAccept }),
+    }, dependencies);
+}
+export function createRoleRuntimeExtension(dependencies) {
+    return (envelopeHost) => {
+        let projectClosedSubmission = async () => {
+            throw new Error("角色终局投射接缝尚未初始化");
+        };
+        const roleHost = createSubmissionLedgerHost(envelopeHost.host, new Map(PACKAGED_ROLE_REGISTRY.map(({ role, outputTool }) => [outputTool, role])), failInfrastructure, async (projection, context) => projectClosedSubmission(projection, context));
+        roleHost.registerFlag(ROLE_FLAG.name, ROLE_FLAG.definition);
+        // Reviewer transport flags: shared envelope owns registration (ADR 0018).
+        for (const flag of REVIEWER_TRANSPORT_FLAGS) {
+            roleHost.registerFlag(flag.name, flag.definition);
+        }
+        for (const flag of NOTARY_TRANSPORT_FLAGS) {
+            roleHost.registerFlag(flag.name, flag.definition);
+        }
+        for (const flag of GLEANER_LEFT_TRANSPORT_FLAGS) {
+            roleHost.registerFlag(flag.name, flag.definition);
+        }
+        for (const flag of DIARIST_TRANSPORT_FLAGS) {
+            roleHost.registerFlag(flag.name, flag.definition);
+        }
+        let admitted = false;
+        let selectedRole;
+        /** Live Reviewer parent activation for envelope agent_start prompt assembly. */
+        let activeReviewerParent;
+        /** Envelope-owned Reviewer Skill expansion state (ADR 0018 — not a role-module facade). */
+        let reviewerOriginalRequest;
+        let reviewerExpansionCaptured = false;
+        let navigatorAttendance;
+        // #351: session-lifecycle owner for periodic OAuth refresh (orthogonal to role admission).
+        let pendingNavigatorPresentation;
+        let pendingNavigatorSettlement;
+        let navigatorWorkContext;
+        /** toolCallId → fact+evidence; one-shot projected onto durable tool_result (#475). */
+        const pendingInfrastructureFailures = new Map();
+        // Envelope-owned execute→tool_result bridge for submission non-pass (ADR 0018 / #525).
+        const pendingSubmissionNonPassByToolCallId = new Map();
+        let engineDetourRegistered = false;
+        // #288 primary-session thin adapter. The policy is the sole budget owner;
+        // terminating-tool rejections and mechanical delivery requests share two turns.
+        let receiptDelivery = createReceiptDeliveryPolicy();
+        let noReceiptRecorded = false;
+        // Public-run fetch observation (in-process-session statusAwareFetch face).
+        let priorFetch;
+        let fetchWrapped = false;
+        const settleNavigatorProjection = async (settlement) => {
+            const attendance = navigatorAttendance;
+            if (settlement === undefined || attendance === undefined)
+                return;
+            const workContext = navigatorWorkContext;
+            const pending = (async () => {
+                if (settlement.kind !== "accepted") {
+                    await attendance.settle(settlement);
+                    return;
+                }
+                const settlePromise = attendance.settle(settlement);
+                // Attach catch immediately so a late rejection after grace timeout cannot
+                // surface as unhandledRejection / stale-ctx after session dispose (#675).
+                void settlePromise.catch(() => undefined);
+                const raced = await raceNavigatorGrace(settlePromise, NAVIGATOR_POST_ROLE_GRACE_MS);
+                if (raced.status !== "timeout")
+                    return;
+                if (pendingNavigatorPresentation === undefined) {
+                    const routePlaybookReadFailure = attendance.knownRoutePlaybookReadFailure?.();
+                    const report = {
+                        disposition: "unavailable",
+                        unavailableReason: "Navigator exceeded post-role delivery grace",
+                        unavailableSource: "unknown",
+                        unavailableCause: "unknown",
+                        ...(routePlaybookReadFailure === undefined ? {} : { routePlaybookReadFailure }),
+                    };
+                    const event = {
+                        version: 1,
+                        disposition: "unavailable",
+                        invocationId: "post-role-grace-timeout",
+                        role: settlement.role,
+                        phase: settlement.phase,
+                        subjectKey: workContext?.subjectKey ?? "",
+                        unavailableReason: "Navigator exceeded post-role delivery grace",
+                        unavailableSource: "unknown",
+                        unavailableCause: "unknown",
+                        ...(routePlaybookReadFailure === undefined ? {} : { routePlaybookReadFailure }),
+                    };
+                    pendingNavigatorPresentation = { event, report };
+                }
+                await attendance.dispose();
+            })();
+            pendingNavigatorSettlement = pending;
+            await pending;
+        };
+        projectClosedSubmission = async (projection, context) => projectClosedSubmissionLifecycle(projection, context, navigatorPhase(roleHost, projection.role), () => receiptDelivery.recordAccepted(), settleNavigatorProjection);
+        roleHost.on("input", (event) => {
+            const role = roleHost.getFlag(ROLE_FLAG.name);
+            if (role !== undefined && !admitted)
+                return { action: "handled" };
+            // Envelope exclusively owns Reviewer Skill invocation transform + original-request capture.
+            if (role === "reviewer"
+                && admitted
+                && activeReviewerParent !== undefined
+                && reviewerOriginalRequest === undefined) {
+                reviewerOriginalRequest = event.text;
+                return {
+                    action: "transform",
+                    text: activeReviewerParent.skillBinding.invocation(event.text),
+                    ...(event.images === undefined ? {} : { images: event.images }),
+                };
+            }
+            return { action: "continue" };
+        });
+        roleHost.on("before_agent_start", async (event, ctx) => {
+            const role = roleHost.getFlag(ROLE_FLAG.name);
+            if (role === undefined)
+                return;
+            if (!admitted || selectedRole !== role) {
+                failInfrastructure(new ActivationBarrierError(role), ctx);
+            }
+            // Notary session bound: envelope-owned lifecycle write (ADR 0018 / #582).
+            // Ticket flag register/read + session entry live here; role projects admitted bound only.
+            if (role === "notary") {
+                const bound = projectNotaryBoundFromFlags((name) => roleHost.getFlag(name));
+                if (bound !== undefined) {
+                    ctx.sessionManager.appendCustomEntry?.(NOTARY_SESSION_BOUND_ENTRY, bound);
+                }
+            }
+            if (navigatorAttendance !== undefined && navigatorWorkContext !== undefined && navigatorWorkContext.contextError === undefined) {
+                // Flagged roles already have a concrete packet/task/case/review input.
+                // A bare Judge (and other bare packaged entrypoint) gets its concrete
+                // user task at this seam; do not copy the assembled system prompt.
+                // Replacement is keyed by typed subject provenance, never prose prefixes.
+                // Soft session_start placeholders (no materials yet) recover here; hard
+                // contextError from true loader failures stays poisoned and honest.
+                if (navigatorWorkContext.subjectProvenance === "placeholder") {
+                    const subject = event.prompt.trim();
+                    if (subject !== "") {
+                        const root = subjectPath(ctx.sessionManager.getSessionDir(), ctx.cwd);
+                        const subjectProvenance = "user_prompt";
+                        const priorAuthority = navigatorWorkContext.authority;
+                        const authority = typeof priorAuthority === "string" && priorAuthority.trim() !== ""
+                            ? priorAuthority
+                            : subject;
+                        navigatorWorkContext = {
+                            subjectKey: navigatorSubjectKey(root, subject, subjectProvenance),
+                            subject,
+                            authority,
+                            subjectProvenance,
+                        };
+                        await navigatorAttendance.setWorkContext(navigatorWorkContext);
+                    }
+                }
+            }
+            navigatorAttendance?.prepare();
+            // Envelope-owned Reviewer expansion capture + parent prompt assembly (no role-module callback).
+            if (role === "reviewer" && activeReviewerParent !== undefined) {
+                if (!reviewerExpansionCaptured) {
+                    if (reviewerOriginalRequest === undefined
+                        || activeReviewerParent.skillBinding.captureExpansion(roleHost.capabilities?.skillExpansion(event.prompt), reviewerOriginalRequest) === undefined) {
+                        failInfrastructure(new Error("Canonical code-review Skill expansion did not match the captured request"), ctx);
+                    }
+                    reviewerExpansionCaptured = true;
+                }
+                const specDisposition = activeReviewerParent.getSpecDisposition();
+                return {
+                    systemPrompt: assembleReviewerParentSystemPrompt({
+                        baseSystemPrompt: event.systemPrompt,
+                        soul: activeReviewerParent.soul,
+                        ...(specDisposition === undefined ? {} : { specDisposition }),
+                    }),
+                };
+            }
+        });
+        roleHost.on("tool_result", async (event) => {
+            const role = selectedRole;
+            if (role === undefined)
+                return;
+            const pendingInfra = pendingInfrastructureFailures.get(event.toolCallId);
+            const isRoleInfrastructureFailure = pendingInfra !== undefined;
+            if (pendingInfra !== undefined)
+                pendingInfrastructureFailures.delete(event.toolCallId);
+            // One-shot project fact + typed evidence so live settlement and durable session agree.
+            const infrastructureDetails = pendingInfra?.details;
+            const classified = infrastructureDetails === undefined
+                ? event
+                : { ...event, details: infrastructureDetails };
+            const isOutputTool = event.toolName === navigatorOutputTool(role);
+            const outputClassification = isOutputTool ? classifyPackagedRoleTerminalResult(classified) : undefined;
+            if (isRoleInfrastructureFailure || outputClassification?.kind === "infrastructure") {
+                receiptDelivery.stopForInfrastructure();
+            }
+            else if (isOutputTool && outputClassification?.kind === "nonterminal" && event.isError) {
+                const reason = (event.content ?? [])
+                    .map((part) => part.type === "text" && "text" in part ? part.text : "")
+                    .join("")
+                    .trim() || "terminating tool rejected";
+                receiptDelivery.recordRejected(reason);
+            }
+            // Accepted/human terminal projection belongs exclusively to typed ledger
+            // closure. tool_result retains only infrastructure settlement.
+            const settlement = isRoleInfrastructureFailure || outputClassification?.kind === "infrastructure"
+                ? publicNavigatorSettlement(role, navigatorPhase(roleHost, role), classified)
+                : undefined;
+            await settleNavigatorProjection(settlement);
+            // Persist typed infrastructure-failure fact onto the role session toolResult so
+            // exact-session restart shares the same durable completion classification.
+            if (infrastructureDetails !== undefined) {
+                return { details: infrastructureDetails, isError: true };
+            }
+            // Submission non-pass: throw kept message text for the model; project the
+            // envelope-bound structured result onto session details at this tool_result seam.
+            const submissionNonPass = pendingSubmissionNonPassByToolCallId.get(event.toolCallId);
+            if (submissionNonPass !== undefined) {
+                pendingSubmissionNonPassByToolCallId.delete(event.toolCallId);
+                return { details: submissionNonPass, isError: true };
+            }
+            // Recommendation rides the accepted settlement record's content so the one
+            // mandatory last-ak_*_output extraction surfaces route/next/reason without
+            // a second file, grep, or nesting step. Receipt details stay contract-pure;
+            // unavailable/no-advice leave the settlement untouched.
+            if (event.isError)
+                return;
+            const decorated = decorateSettlementWithNavigation(event, pendingNavigatorPresentation);
+            if (decorated === undefined)
+                return;
+            return {
+                content: decorated.content,
+            };
+        });
+        // Queue receipt delivery before `agent_settled`: that event means Pi has
+        // already decided no queued continuation will run, so a triggerTurn there is
+        // too late for print/json sessions. `agent_end` is the last production seam
+        // whose queued next turn is consumed before settlement.
+        roleHost.on("agent_end", (event, ctx) => {
+            const lastMessage = event.messages.at(-1);
+            if (lastMessage?.role === "assistant"
+                && (lastMessage.stopReason === "error" || lastMessage.stopReason === "aborted")) {
+                // Provider failure/abort has no tool_result event; classify it here so the
+                // receipt policy cannot turn infrastructure death into an exit-0 lifecycle.
+                receiptDelivery.stopForInfrastructure();
+                return;
+            }
+            if (receiptDelivery.nextAction() === "request-delivery") {
+                receiptDelivery.recordDeliveryRequest();
+                // Keep the package-owned continuation off the public input lifecycle:
+                // receipt delivery must not be mistaken for later caller input.
+                envelopeHost.appendEntry("ak-receipt-delivery-request");
+                try {
+                    sitianReport({
+                        level: "event",
+                        kind: "receipt-delivery",
+                        cwd: ctx.cwd,
+                        sessionParent: ctx.sessionManager.getSessionFile(),
+                        payload: { type: "ak-receipt-delivery-request" },
+                        source: "role-runtime",
+                    });
+                }
+                catch { }
+                envelopeHost.sendMessage({
+                    customType: "ak-receipt-delivery-prompt",
+                    content: RECEIPT_DELIVERY_PROMPT,
+                    display: false,
+                }, { triggerTurn: true, deliverAs: "followUp" });
+            }
+            else if (receiptDelivery.nextAction() === "no-receipt" && !noReceiptRecorded) {
+                const runPointer = process.env.AK_ROLE_RUN_DIR;
+                if (runPointer !== undefined) {
+                    noReceiptRecorded = true;
+                    const facts = receiptDelivery.facts({ runPointer, attemptPointer: `current:${runPointer}` });
+                    envelopeHost.appendEntry(NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, facts);
+                    try {
+                        sitianReport({
+                            level: "event",
+                            kind: "no-receipt-lifecycle",
+                            cwd: ctx.cwd,
+                            sessionParent: ctx.sessionManager.getSessionFile(),
+                            payload: facts,
+                            source: "role-runtime",
+                        });
+                    }
+                    catch { }
+                }
+            }
+        });
+        roleHost.on("agent_settled", async () => {
+            if (pendingNavigatorSettlement !== undefined) {
+                await pendingNavigatorSettlement;
+            }
+            // Do not auto-drain Navigator on ordinary mid-turn agent_settled.
+            // Multi-turn roles (#162 coder) fire agent_settled after every tool turn;
+            // discarding a healthy/in-flight prepare there forces a cold prepare on the
+            // final accepted terminal and races the post-role grace. Keep preparation
+            // until an accepted/human/infrastructure tool_result settlement (or dispose).
+            // Provider death without any role tool_result leaves preparation held; the
+            // next explicit settlement or session end owns it — not mid-turn churn.
+            pendingNavigatorSettlement = undefined;
+            const presentation = pendingNavigatorPresentation;
+            pendingNavigatorPresentation = undefined;
+            if (presentation === undefined)
+                return;
+            await envelopeHost.sendMessage({
+                customType: NAVIGATOR_EVENT_TYPE,
+                content: formatNavigatorReport(presentation.report),
+                display: true,
+                details: presentation.event,
+            }, { triggerTurn: false });
+        });
+        roleHost.on("session_shutdown", async () => {
+            // #351: stop OAuth keepalive first so shutdown yields zero further ticks.
+            envelopeHost.stopKeepalive();
+            if (fetchWrapped && priorFetch !== undefined) {
+                globalThis.fetch = priorFetch;
+                priorFetch = undefined;
+                fetchWrapped = false;
+            }
+            // Flush any still-pending affirmative attendance before teardown. Accepted
+            // grace-timeout paths normally emit on agent_settled; abort can skip that hook.
+            const presentation = pendingNavigatorPresentation;
+            pendingNavigatorPresentation = undefined;
+            if (presentation !== undefined) {
+                try {
+                    await envelopeHost.sendMessage({
+                        customType: NAVIGATOR_EVENT_TYPE,
+                        content: formatNavigatorReport(presentation.report),
+                        display: true,
+                        details: presentation.event,
+                    }, { triggerTurn: false });
+                }
+                catch {
+                    // Teardown must not mask the original role failure cause.
+                }
+            }
+            await navigatorAttendance?.dispose();
+            navigatorAttendance = undefined;
+            pendingNavigatorSettlement = undefined;
+            pendingInfrastructureFailures.clear();
+            pendingSubmissionNonPassByToolCallId.clear();
+            observationFace.reset();
+        });
+        const hostActions = {
+            failInfrastructure(error, ctx, toolCallId) {
+                if (toolCallId !== undefined) {
+                    pendingInfrastructureFailures.set(toolCallId, buildPendingInfrastructureFailure(error));
+                }
+                failInfrastructure(error, ctx);
+            },
+            bindSubmissionNonPass(toolCallId, result) {
+                pendingSubmissionNonPassByToolCallId.set(toolCallId, result);
+            },
+        };
+        const judge = createJudgeRoleRuntime(roleHost, {
+            loadSoul: dependencies.loadJudgeSoul,
+            auditSoulCompliance: dependencies.auditSoulCompliance,
+        }, hostActions);
+        const fixer = createFixerRoleRuntime(roleHost, {
+            async loadSoul() {
+                if (dependencies.loadFixerSoul === undefined) {
+                    throw new Error("fixer soul loader is not configured");
+                }
+                return dependencies.loadFixerSoul();
+            },
+            async loadPacket(path) {
+                if (dependencies.loadFixPacket === undefined) {
+                    throw new Error("Fixer packet loader is not configured");
+                }
+                return dependencies.loadFixPacket(path);
+            },
+        }, hostActions);
+        const coder = createCoderRoleRuntime(roleHost, {
+            async loadSoul() {
+                if (dependencies.loadCoderSoul === undefined) {
+                    throw new Error("coder soul loader is not configured");
+                }
+                return dependencies.loadCoderSoul();
+            },
+            async loadTask(path) {
+                if (dependencies.loadCoderTask === undefined) {
+                    throw new Error("Coder task loader is not configured");
+                }
+                return dependencies.loadCoderTask(path);
+            },
+            ...(dependencies.loadCanonicalSkillBinding === undefined
+                ? {}
+                : {
+                    loadCanonicalSkillBinding: (name) => dependencies.loadCanonicalSkillBinding(name),
+                }),
+        }, hostActions);
+        const reviewer = createReviewerRoleRuntime(roleHost, {
+            async loadSoul() {
+                if (dependencies.loadReviewerSoul === undefined) {
+                    throw new Error("reviewer soul loader is not configured");
+                }
+                return dependencies.loadReviewerSoul();
+            },
+            async createPinnedGitReader() {
+                if (dependencies.createReviewerPinnedGitReader === undefined)
+                    throw new Error("Reviewer runtime dependencies are not configured");
+                return dependencies.createReviewerPinnedGitReader();
+            },
+            async loadCanonicalSkillBinding(name) {
+                if (dependencies.loadCanonicalSkillBinding === undefined) {
+                    throw new Error("Reviewer runtime dependencies are not configured");
+                }
+                return dependencies.loadCanonicalSkillBinding(name);
+            },
+            ...(dependencies.createReviewerIssueFetcher === undefined
+                ? {}
+                : { fetchIssue: dependencies.createReviewerIssueFetcher() }),
+            async runDispatch(dispatch, options) {
+                if (dependencies.runReviewerDispatch === undefined)
+                    throw new Error("Reviewer runtime dependencies are not configured");
+                return dependencies.runReviewerDispatch(dispatch, options);
+            },
+            ...(dependencies.shutdownReviewerAgent === undefined
+                ? {}
+                : { shutdownAgent: dependencies.shutdownReviewerAgent }),
+        }, hostActions);
+        const doctor = createDoctorRoleRuntime(roleHost, {
+            async loadSoul() { if (!dependencies.loadDoctorSoul)
+                throw new Error("Doctor runtime dependencies are not configured"); return dependencies.loadDoctorSoul(); },
+            async loadCase(path) { if (!dependencies.loadDoctorCase)
+                throw new Error("Doctor runtime dependencies are not configured"); return dependencies.loadDoctorCase(path); },
+            async auditCompliance(options) { if (!dependencies.auditDoctorCompliance)
+                throw new Error("Doctor runtime dependencies are not configured"); return dependencies.auditDoctorCompliance(options); },
+        }, hostActions);
+        const notary = createNotaryRoleRuntime(roleHost, {
+            async loadSoul() {
+                if (!dependencies.loadNotarySoul)
+                    throw new Error("Notary runtime dependencies are not configured");
+                return dependencies.loadNotarySoul();
+            },
+            async loadSourceRunLocator(path) {
+                if (!dependencies.loadNotarySourceRun)
+                    throw new Error("Notary runtime dependencies are not configured");
+                return dependencies.loadNotarySourceRun(path);
+            },
+        }, hostActions);
+        const countersign = createCountersignRoleRuntime(roleHost, {
+            async loadSoul() {
+                if (!dependencies.loadCountersignSoul)
+                    throw new Error("Countersign runtime dependencies are not configured");
+                return dependencies.loadCountersignSoul();
+            },
+        }, hostActions);
+        const gleanerLeftRuntime = createGleanerLeftRoleRuntime(roleHost, {
+            async loadSoul() {
+                if (!dependencies.loadGleanerLeftSoul)
+                    throw new Error("Gleaner-left runtime dependencies are not configured");
+                return dependencies.loadGleanerLeftSoul();
+            },
+        });
+        const gleanerLeft = {
+            async activate() {
+                decodeGleanerLeftBase((name) => envelopeHost.host.getFlag(name));
+                return gleanerLeftRuntime.activate();
+            },
+        };
+        const inspector = createInspectorRoleRuntime(roleHost, {
+            async loadSoul() {
+                if (!dependencies.loadInspectorSoul)
+                    throw new Error("Inspector runtime dependencies are not configured");
+                return dependencies.loadInspectorSoul();
+            },
+        });
+        const gatekeeper = createGatekeeperRoleRuntime(roleHost, {
+            async loadSoul() {
+                if (!dependencies.loadGatekeeperSoul)
+                    throw new Error("Gatekeeper runtime dependencies are not configured");
+                return dependencies.loadGatekeeperSoul();
+            },
+        });
+        const navigator = createNavigatorRoleRuntime(roleHost, {
+            async loadSoul() {
+                if (!dependencies.loadNavigatorSoul)
+                    throw new Error("Navigator runtime dependencies are not configured");
+                return dependencies.loadNavigatorSoul();
+            },
+        });
+        const auditor = createAuditorRoleRuntime(roleHost, {
+            async loadSoul() {
+                if (!dependencies.loadAuditorSoul)
+                    throw new Error("Auditor runtime dependencies are not configured");
+                return dependencies.loadAuditorSoul();
+            },
+        });
+        const diarist = createDiaristRoleRuntime(roleHost, {
+            async loadSoul() {
+                if (!dependencies.loadDiaristSoul)
+                    throw new Error("Diarist runtime dependencies are not configured");
+                return dependencies.loadDiaristSoul();
+            },
+        }, () => envelopeHost.host.getFlag(DIARIST_SOURCES_FLAG.name));
+        let sessionMergerGitState = dependencies.mergerGitState;
+        const merger = createMergerRoleRuntime(roleHost, {
+            async loadSoul() { if (!dependencies.loadMergerSoul)
+                throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerSoul(); },
+            async loadInput(path) { if (!dependencies.loadMergerInput)
+                throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerInput(path); },
+            gitState: {
+                activeMerge() { if (!sessionMergerGitState)
+                    throw new Error("Merger runtime dependencies are not configured"); return sessionMergerGitState.activeMerge(); },
+                completedMerge(mergeCommitId, automaticMergeTreeId) { if (!sessionMergerGitState)
+                    throw new Error("Merger runtime dependencies are not configured"); return sessionMergerGitState.completedMerge(mergeCommitId, automaticMergeTreeId); },
+            },
+        }, hostActions);
+        const collector = createCollectorRoleRuntime(roleHost, {
+            async loadSoul() {
+                if (dependencies.loadCollectorSoul === undefined) {
+                    throw new Error("collector soul loader is not configured");
+                }
+                return dependencies.loadCollectorSoul();
+            },
+            createTransport() {
+                if (dependencies.createCollectorTransport === undefined) {
+                    throw new Error("Collector GitHub transport is not configured");
+                }
+                return dependencies.createCollectorTransport();
+            },
+            createLedger(config, collectorClock, context) {
+                const append = context.sessionManager?.appendCustomEntry;
+                return createCollectorLedger(config, {
+                    clock: collectorClock,
+                    ...(append === undefined
+                        ? {}
+                        : {
+                            journal: {
+                                append(customType, data) {
+                                    context.sessionManager?.appendCustomEntry?.(customType, data);
+                                },
+                            },
+                        }),
+                    dossierEntries: context.sessionManager?.getEntries?.() ?? [],
+                });
+            },
+            ...(dependencies.createCollectorClock === undefined
+                ? {}
+                : { createClock: dependencies.createCollectorClock }),
+            ...(dependencies.collectorPackageExtensionPath === undefined
+                ? {}
+                : {
+                    packageExtensionPath: dependencies.collectorPackageExtensionPath,
+                }),
+        }, hostActions);
+        const clock = dependencies.activationClock ?? (() => new Date().toISOString());
+        const writeTrace = dependencies.activationTraceWriter ?? writeActivationTraceRecord;
+        const observationFace = createToolExecutionObservationFace({
+            role: () => selectedRole,
+            admitted: () => admitted,
+            clock: dependencies.toolExecutionObservationClock ?? clock,
+            monoNow: dependencies.toolExecutionObservationMonoNow ?? systemToolExecutionObservationMonoNow,
+            write: dependencies.toolExecutionObservationWriter ?? writeToolExecutionObservationRecord,
+        });
+        // ExtensionRunner.emit catches ordinary handler throws, emits extension error, and continues.
+        // Observation plane failures must still hit the shared infrastructure termination path
+        // (abort + nonzero print/json exit) with the original cause before that swallow.
+        const observe = async (run, ctx) => {
+            try {
+                await run();
+            }
+            catch (error) {
+                failInfrastructure(error, ctx);
+            }
+        };
+        roleHost.on("tool_execution_start", async (event, ctx) => {
+            await observe(() => observationFace.onStart(event), ctx);
+        });
+        roleHost.on("tool_execution_update", async (event, ctx) => {
+            await observe(() => observationFace.onUpdate(event), ctx);
+        });
+        roleHost.on("tool_execution_end", async (event, ctx) => {
+            await observe(() => observationFace.onEnd(event), ctx);
+        });
+        // Public Role run: record typed non-success HTTP for error evidence + v1 resume.
+        // Same observation owner as in-process-session statusAwareFetch → typed-provider-http
+        // sidecar (settlement already merges observation.httpStatus into knownFailure).
+        // after_provider_response covers the success-path onResponse face; fetch wrap covers
+        // non-2xx Responses where openai-completions throws before onResponse (#675).
+        const recordHttpObservation = async (status, provider, ctx) => {
+            const runDir = process.env.AK_ROLE_RUN_DIR;
+            if (typeof runDir !== "string" || runDir.trim() === "")
+                return;
+            try {
+                await recordTypedProviderHttpStatus(runDir, { httpStatus: status, provider });
+            }
+            catch (error) {
+                if (status >= 200 &&
+                    status < 300 &&
+                    error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT") {
+                    return;
+                }
+                failInfrastructure(error, ctx);
+            }
+        };
+        roleHost.on("after_provider_response", async (event, ctx) => {
+            const status = event.status;
+            if (typeof status !== "number")
+                return;
+            const fromCtx = ctx.model?.provider;
+            const provider = typeof fromCtx === "string" && fromCtx.trim() !== ""
+                ? fromCtx
+                : "unknown";
+            await recordHttpObservation(status, provider, ctx);
+        });
+        roleHost.on("session_start", async (event, ctx) => {
+            // Scope fetch observation to this public run (in-process-session statusAwareFetch face).
+            if (!fetchWrapped && typeof globalThis.fetch === "function") {
+                priorFetch = globalThis.fetch.bind(globalThis);
+                const underlying = priorFetch;
+                globalThis.fetch = (async (input, init) => {
+                    const response = await underlying(input, init);
+                    const runDir = process.env.AK_ROLE_RUN_DIR;
+                    if (typeof runDir === "string"
+                        && runDir.trim() !== ""
+                        && typeof response?.status === "number"
+                        && (response.status < 200 || response.status >= 300)) {
+                        const provider = typeof ctx.model?.provider === "string" && ctx.model.provider.trim() !== ""
+                            ? ctx.model.provider
+                            : "unknown";
+                        try {
+                            await recordTypedProviderHttpStatus(runDir, {
+                                httpStatus: response.status,
+                                provider,
+                            });
+                        }
+                        catch {
+                            // Observation must not break the provider stream (same as in-process-session).
+                        }
+                    }
+                    return response;
+                });
+                fetchWrapped = true;
+            }
+            admitted = false;
+            selectedRole = undefined;
+            activeReviewerParent = undefined;
+            reviewerOriginalRequest = undefined;
+            reviewerExpansionCaptured = false;
+            receiptDelivery = createReceiptDeliveryPolicy();
+            noReceiptRecorded = false;
+            observationFace.reset();
+            pendingNavigatorPresentation = undefined;
+            pendingNavigatorSettlement = undefined;
+            pendingInfrastructureFailures.clear();
+            pendingSubmissionNonPassByToolCallId.clear();
+            navigatorWorkContext = undefined;
+            // #351: OAuth keepalive is orthogonal to --ak-role; start before role early-return
+            // so role-less sessions (and reload after shutdown stop) still keep tokens alive.
+            envelopeHost.startKeepalive(ctx);
+            const rawRole = roleHost.getFlag(ROLE_FLAG.name);
+            if (rawRole === undefined)
+                return;
+            const entry = PACKAGED_ROLE_REGISTRY.find(({ role }) => role === rawRole);
+            if (entry === undefined) {
+                failInfrastructure(new Error(`Unsupported workflow role: ${String(rawRole)}`), ctx);
+            }
+            selectedRole = entry.role;
+            await navigatorAttendance?.dispose();
+            navigatorAttendance = undefined;
+            const runtime = {
+                event,
+                context: ctx,
+                judge,
+                fixer,
+                coder,
+                reviewer,
+                decodeReviewerAdmitted() {
+                    return decodeReviewerAdmittedInputs((name) => roleHost.getFlag(name));
+                },
+                bindReviewerParent(activation) {
+                    activeReviewerParent = activation;
+                },
+                decodeNotaryAdmitted() {
+                    const ticketNumber = readNotaryTicketFlag(roleHost.getFlag(NOTARY_TICKET_FLAG.name));
+                    return ticketNumber === undefined ? undefined : { ticketNumber };
+                },
+                collector,
+                doctor,
+                notary,
+                countersign,
+                gleanerLeft,
+                inspector,
+                gatekeeper,
+                navigator,
+                auditor,
+                diarist,
+                merger: async () => {
+                    if (dependencies.mergerGitState === undefined) {
+                        sessionMergerGitState = dependencies.createMergerGitState?.(ctx.cwd);
+                    }
+                    if (sessionMergerGitState === undefined)
+                        throw new Error("Merger runtime dependencies are not configured");
+                    await merger.activate();
+                },
+            };
+            try {
+                // Production topology only (ADR 0048/0049): no test-only ledger hooks.
+                // Admit durable session file first so lifecycle getEntries/appendEntry are truthful:
+                // deferred SM materialization must not wipe an in-memory principal marker.
+                const bookKey = resolveBookKeyFromGit(ctx.cwd);
+                const correlation = correlationIdentityFromEnv();
+                const sessionFile = ctx.sessionManager.getSessionFile?.() || ctx.sessionManager.getSessionDir?.();
+                const ledgerHome = resolveActivationLedgerHomeForPath(sessionFile);
+                const session = durableSessionPointer(ctx.sessionManager);
+                // Same public activation face for every role (#675 / owner 09-06): no nested-env
+                // skip, no work-role whitelist. Attendance attaches when the envelope supplies it.
+                // Navigator seat never re-attaches itself — prepare turns already ARE the navigator
+                // public activation (prevents summonPublicRole navigator ↔ attendance recursion).
+                if (dependencies.createNavigatorAttendance !== undefined
+                    && entry.role !== "navigator") {
+                    let work;
+                    let contextError;
+                    if (dependencies.loadNavigatorWorkContext === undefined) {
+                        const fallbackSubjectKey = subjectPath(ctx.sessionManager.getSessionDir(), ctx.cwd);
+                        contextError = new Error("Navigator work context loader is not configured");
+                        work = { subjectKey: fallbackSubjectKey, subject: `work subject: ${fallbackSubjectKey}`, authority: "", subjectProvenance: "placeholder" };
+                    }
+                    else {
+                        try {
+                            work = await dependencies.loadNavigatorWorkContext({
+                                context: ctx,
+                                role: entry.role,
+                                phase: navigatorPhase(roleHost, entry.role),
+                                getFlag: (name) => roleHost.getFlag(name),
+                            });
+                            contextError = work.contextError;
+                        }
+                        catch (error) {
+                            // Contract: README.md#Navigator-attendance — a failed context load continues with a typed placeholder work context; the original cause is retained in contextError for the typed unavailable report.
+                            contextError = navigatorUnavailableError("context", error);
+                            const fallbackSubjectKey = subjectPath(ctx.sessionManager.getSessionDir(), ctx.cwd);
+                            work = { subjectKey: fallbackSubjectKey, subject: `work subject: ${fallbackSubjectKey}`, authority: "", subjectProvenance: "placeholder" };
+                        }
+                    }
+                    navigatorWorkContext = { ...work, ...(contextError === undefined ? {} : { contextError }) };
+                    // Shared envelope owns exact invocation principal from admitted session lifecycle.
+                    // session_start is process activation: resume unfinished principal only when marker
+                    // role/phase/subjectKey still match; mint for contradictory marker, malformed nearest,
+                    // missing marker, or terminal already completed.
+                    const sessionEntries = [...ctx.sessionManager.getEntries()];
+                    const invocationPhase = navigatorPhase(roleHost, entry.role);
+                    const lifecyclePrincipal = resolveLifecycleInvocationPrincipal(sessionEntries, {
+                        role: entry.role,
+                        phase: invocationPhase,
+                        subjectKey: work.subjectKey,
+                    });
+                    const invocationId = lifecyclePrincipal.invocationId;
+                    if (!lifecyclePrincipal.resume) {
+                        const data = {
+                            invocationId,
+                            role: entry.role,
+                            phase: invocationPhase,
+                            subjectKey: work.subjectKey,
+                        };
+                        envelopeHost.appendEntry(NAVIGATOR_INVOCATION_ENTRY, data);
+                        try {
+                            sitianReport({
+                                level: "event",
+                                kind: "attendance",
+                                cwd: ctx.cwd,
+                                sessionParent: ctx.sessionManager.getSessionFile(),
+                                payload: { type: NAVIGATOR_INVOCATION_ENTRY, ...data },
+                                source: "role-runtime",
+                            });
+                        }
+                        catch { }
+                    }
+                    navigatorAttendance = await dependencies.createNavigatorAttendance({
+                        context: ctx,
+                        role: entry.role,
+                        phase: invocationPhase,
+                        subjectKey: work.subjectKey,
+                        subject: work.subject,
+                        authority: work.authority,
+                        invocationId,
+                        ...(contextError === undefined ? {} : { contextError }),
+                        onEvent: (navigatorEvent, report) => {
+                            pendingNavigatorPresentation = { event: navigatorEvent, report };
+                        },
+                    });
+                    // Warm live help during activation so prepare is not help-bound under load.
+                    // Concrete work context also starts full preparation so session create
+                    // overlaps the role run. Placeholder subjects wait for before_agent_start
+                    // (user prompt may replace the subject key) but still inherit warm help.
+                    navigatorAttendance.warmHelp?.();
+                    if (navigatorWorkContext.contextError === undefined &&
+                        navigatorWorkContext.subjectProvenance !== "placeholder") {
+                        navigatorAttendance.prepare();
+                    }
+                }
+                await executeActivationStage(entry.role, activationStage(entry.role, runtime), { clock, writeTrace });
+                // #357 T2 / #378 / #380 / #391: any role+engine activation registers the package detour tool once.
+                // Gate is env presence only — no per-engine execute branch; no role-module spawn.
+                if (!engineDetourRegistered) {
+                    engineDetourRegistered = registerEngineDetourTool(roleHost, hostActions);
+                }
+                // Worker gates ①②: arm records baseline and runs private one-shot hook uninstall (ADR 0070).
+                // Parent session feeds #216 createRecordSession so baseline/bounce survive resume.
+                if (entry.role === "coder" || entry.role === "fixer") {
+                    if (entry.role === "coder")
+                        coder.armSubmissionGate(ctx.cwd, ctx.sessionManager);
+                    else
+                        fixer.armSubmissionGate(ctx.cwd, ctx.sessionManager);
+                }
+                appendAcceptedActivationToBook({
+                    ledgerHome,
+                    fact: buildAcceptedActivationFact({
+                        role: entry.role,
+                        observedAt: clock(),
+                        bookKey,
+                        session,
+                        correlation,
+                    }),
+                });
+                admitted = true;
+            }
+            catch (error) {
+                failInfrastructure(error, ctx);
+            }
+        });
+    };
+}