@bradheitmann/odin-sentinel 0.4.7 → 0.4.8

package/dist/src/protocol/service.js

@@ -127,6 +127,12 @@ function classifyProbeText(harness, text) {
         classes.push("BLOCKED_BY_PERMISSION");
     if (harness.toLowerCase() === "pi" && /role|mcp|skill|runtime proof|fiction/.test(safeText))
         classes.push("ROLE_COMPATIBILITY_FAILED");
+    if (/unauthorized|authentication parameter not received in header|missing auth header|auth header not/.test(safeText))
+        classes.push("BLOCKED_BY_AUTH");
+    if (harness.toLowerCase() === "crush" && /unauthorized|authentication parameter|auth header/.test(safeText))
+        classes.push("AUTH_PROVIDER_BLOCKED");
+    if (harness.toLowerCase() === "droid" && /insufficient permission to proceed|re-run with --auto|--auto high/.test(safeText))
+        classes.push("AUTO_HIGH_REQUIRED");
     return [...new Set(classes)];
 }
 function normalizePodCount(pods) {
@@ -170,7 +176,9 @@ export function getStartupPacket(input = {}, repository = getDefaultRepository()
         "use visible role slots only; do not create hidden subagents",
         `bootstrap executive office plus ${pods} development pod${pods === 1 ? "" : "s"}`,
         "state SESSION_OBJECTIVES before product dispatch",
-        "refresh repo status, upstream parity, worktrees, stashes, and topology before lifecycle claims"
+        "refresh repo status, upstream parity, worktrees, stashes, and topology before lifecycle claims",
+        "before implementation, QA acceptance, or ACTIVE_WATCH: produce full-instruction-read proof (path, byte or line count, and sha256 per file) and verify it with scripts/protocol/verify-instruction-read.mjs",
+        "for CMUX dispatch: send text, submit Enter, read the target surface, and confirm processing before treating the message as delivered (input-bar text is not delivery)"
     ];
     const modelProfiles = requireRecord(data.modelProfiles.profiles, "model-profiles.profiles");
     const roleModelProfile = modelProfileKeys(role)
@@ -206,6 +214,7 @@ export function getStartupPacket(input = {}, repository = getDefaultRepository()
         bootReceiptSchema: getBootReceiptSchema(repository),
         teamManifestLocator: "odin://protocol/receipts/team-manifest",
         activeWatch,
+        activationGates: getActivationGates(),
         startupPrompt: [
             "Use ODIN Sentinel coordination.",
             "",
@@ -217,6 +226,8 @@ export function getStartupPacket(input = {}, repository = getDefaultRepository()
             "Before occupant launch, readiness must PASS or be explicitly WAIVED_BY_EXEC_PM / SUBSTITUTION_APPROVED_BY_EXEC_PM.",
             "Valid SCP context source required for governed occupants: native sentinel-coordination-protocol skill, compatible odin-sentinel MCP, or full injected SCP protocol text.",
             "Boot receipt schema: use write_scope: [] for no current write assignment; do not use null.",
+            "Activation gates: before implementation, QA acceptance, or ACTIVE_WATCH, emit a full-instruction-read proof (path, byte/line count, and sha256 per file) and verify it with scripts/protocol/verify-instruction-read.mjs.",
+            "CMUX dispatch is not delivered until you submit with Enter and confirm processing on the target surface; input-bar text is not delivery.",
             "Team manifest locator: odin://protocol/receipts/team-manifest.",
             input.repoPath ? `Repository: ${input.repoPath}` : "Repository: discover from current working directory.",
             `Bootstrap executive office plus ${pods} development pod${pods === 1 ? "" : "s"} unless handoff or user instruction overrides this.`,
@@ -294,6 +305,154 @@ export function getBootReceiptExamples() {
         shadow: { ...base, role: "B/SHADOW-1", authority_layer: "review", team: "B", terminal_locator: "workspace:1 pane:b surface:shadow-1", model_harness: "Droid", may_implement: false, may_qa_accept: false, reports_to: "B/TEAM-PM", staffed_by: "A/EXEC-PM", parent_surface_ref: "pane:b", column_index: 1, team_letter: "B" }
     };
 }
+export const CMUX_DELIVERY_STATES = [
+    "DELIVERED_ACKED",
+    "DELIVERED_NO_ACK",
+    "INPUT_BAR_ONLY",
+    "PANE_BLOCKED_ON_PERMISSION",
+    "PANE_STILL_THINKING"
+];
+const CMUX_DELIVERY_PROOF_FIELDS = [
+    "target_surface_locator",
+    "submitted",
+    "verification_method",
+    "observed_processing_state",
+    "timestamp",
+    "sender_role"
+];
+const INSTRUCTION_READ_PROOF_REQUIRED_FIELDS = ["role", "generated_at", "files"];
+const ACTIVATION_GATE_ROLE_WORK = ["implementation", "QA acceptance", "ACTIVE_WATCH"];
+/**
+ * Validate a CMUX delivery proof. CMUX dispatch is not delivered until the sender submits
+ * with Enter and verifies processing on the target surface; text left in an input bar is
+ * INPUT_BAR_ONLY, not delivery. A submitted=false proof or an INPUT_BAR_ONLY state fails.
+ */
+export function validateCmuxDeliveryProof(proof) {
+    const missing = validateRequiredFields(proof, CMUX_DELIVERY_PROOF_FIELDS);
+    const invalid = validateFieldTypes(proof, {
+        target_surface_locator: "string",
+        submitted: "boolean",
+        verification_method: "string",
+        observed_processing_state: "string",
+        timestamp: "string",
+        sender_role: "string"
+    });
+    const warnings = [];
+    const state = typeof proof.observed_processing_state === "string" ? proof.observed_processing_state : undefined;
+    if (state !== undefined && !CMUX_DELIVERY_STATES.includes(state)) {
+        if (!invalid.includes("observed_processing_state"))
+            invalid.push("observed_processing_state");
+        warnings.push(`observed_processing_state must be one of: ${CMUX_DELIVERY_STATES.join(", ")}`);
+    }
+    if (proof.submitted === false) {
+        invalid.push("submitted");
+        warnings.push("CMUX text was not submitted with Enter; this is INPUT_BAR_ONLY, not delivery. Send Enter and re-read the target surface.");
+    }
+    if (state === "INPUT_BAR_ONLY") {
+        if (!invalid.includes("observed_processing_state"))
+            invalid.push("observed_processing_state");
+        warnings.push("INPUT_BAR_ONLY: text is visible in the target input bar but not processed; not a valid delivery until submitted and confirmed.");
+    }
+    else if (state === "PANE_BLOCKED_ON_PERMISSION") {
+        warnings.push("Target pane received the message but is blocked on a permission/approval prompt; classify and resolve before treating it as actioned.");
+    }
+    else if (state === "DELIVERED_NO_ACK") {
+        warnings.push("Delivered, but no acknowledgement observed yet; revisit on the next poll.");
+    }
+    else if (state === "PANE_STILL_THINKING") {
+        warnings.push("Delivered; target is still processing. Revisit to confirm completion.");
+    }
+    return buildValidationResult(missing, invalid, warnings);
+}
+/**
+ * Validate the shape of a full-instruction-read proof: a role, a generation timestamp, and
+ * a non-empty files[] list where each entry carries a path, a byte or line count, and a
+ * sha256 digest. Disk verification (does the digest still match the file?) is performed by
+ * scripts/protocol/verify-instruction-read.mjs.
+ */
+export function validateInstructionReadProof(proof) {
+    const missing = validateRequiredFields(proof, INSTRUCTION_READ_PROOF_REQUIRED_FIELDS);
+    const invalid = validateFieldTypes(proof, { role: "string", generated_at: "string" });
+    const warnings = [];
+    const files = Array.isArray(proof.files) ? proof.files : undefined;
+    if (files === undefined) {
+        if (!missing.includes("files") && !invalid.includes("files"))
+            invalid.push("files");
+    }
+    else if (files.length === 0) {
+        invalid.push("files");
+        warnings.push("instruction-read proof must list at least one file");
+    }
+    else {
+        files.forEach((entry, index) => {
+            const file = asRecord(entry);
+            if (!stringFieldPresent(file.path))
+                invalid.push(`files.${index}.path`);
+            if (!stringFieldPresent(file.sha256)) {
+                invalid.push(`files.${index}.sha256`);
+                warnings.push(`files.${index} must include a sha256 digest proving full-content coverage`);
+            }
+            const hasBytes = typeof file.bytes === "number" && Number.isFinite(file.bytes);
+            const hasLines = typeof file.lines === "number" && Number.isFinite(file.lines);
+            if (!hasBytes && !hasLines) {
+                invalid.push(`files.${index}.bytes`);
+                warnings.push(`files.${index} must include a byte count or line count`);
+            }
+        });
+    }
+    return buildValidationResult(missing, invalid, warnings);
+}
+/**
+ * Activation-gate guidance for agents using only ODIN MCP resources: how to satisfy CMUX
+ * delivery proof and full-instruction-read proof before acting under SCP.
+ */
+export function getActivationGates() {
+    return {
+        version: VERSION,
+        summary: "Before acting under SCP, prove delivery and prove full instruction reads.",
+        addressesObservedFailStates: [
+            "CMUX standby text left unsubmitted in an input bar (INPUT_BAR_ONLY) mistaken for delivery",
+            "agents reading only the first 50-100 lines of instructions instead of the full sources"
+        ],
+        cmuxDeliveryProof: {
+            requirement: "CMUX dispatch is not delivered until the sender submits with Enter and verifies processing on the target surface. Text visible in an input bar is not delivery.",
+            requiredFields: CMUX_DELIVERY_PROOF_FIELDS,
+            allowedProcessingStates: CMUX_DELIVERY_STATES,
+            confirmedDeliveryStates: ["DELIVERED_ACKED", "DELIVERED_NO_ACK"],
+            senderSteps: [
+                "send the text to the target surface",
+                "submit with Enter (send-key enter)",
+                "read the target surface",
+                "confirm the agent processed or acknowledged the message"
+            ],
+            validateWith: "odin.validate_cmux_delivery_proof",
+            example: {
+                target_surface_locator: "workspace:1 pane:b surface:qa-1",
+                submitted: true,
+                verification_method: "cmux read-screen",
+                observed_processing_state: "DELIVERED_ACKED",
+                timestamp: "2026-01-01T00:00:00Z",
+                sender_role: "A/EXEC-PM"
+            }
+        },
+        instructionReadProof: {
+            requirement: `Activated roles must produce full-instruction-read proof before ${ACTIVATION_GATE_ROLE_WORK.join(", ")} work. First-screen, head, or partial reads are insufficient.`,
+            requiredFields: INSTRUCTION_READ_PROOF_REQUIRED_FIELDS,
+            perFileFields: ["path", "bytes or lines", "sha256"],
+            verifierScript: "scripts/protocol/verify-instruction-read.mjs",
+            installerScript: "scripts/protocol/install-activation-hooks.mjs",
+            verifyCommand: "node scripts/protocol/verify-instruction-read.mjs <proof.json>",
+            recordCommand: "node scripts/protocol/verify-instruction-read.mjs --record <file...> > proof.json",
+            validateWith: "odin.validate_instruction_read_proof",
+            example: {
+                schema: "odin.instruction_read_proof.v1",
+                role: "B/DEV-1",
+                generated_at: "2026-01-01T00:00:00Z",
+                files: [{ path: "protocol/SCP.md", bytes: 4175, lines: 87, sha256: "<sha256-digest>" }]
+            }
+        }
+    };
+}
 export function getDelegationPacket(input) {
     return {
         receipt_type: "SCP-DELEGATE",
@@ -314,7 +473,16 @@ export function getDelegationPacket(input) {
             delivery_proof_required: true
         },
         report_back: input.reportBack ?? "Return status, evidence path, blockers, touched files, and next requested action.",
-        required_delivery_states: ["DELIVERED_ACKED", "DELIVERED_NO_ACK", "INPUT_BAR_ONLY", "PANE_BLOCKED_ON_PERMISSION", "PANE_STILL_THINKING"]
+        required_delivery_states: [...CMUX_DELIVERY_STATES],
+        delivery_proof_contract: {
+            required: true,
+            reason: "CMUX dispatch is not delivered until submitted with Enter and confirmed on the target surface; input-bar text is not delivery.",
+            required_fields: CMUX_DELIVERY_PROOF_FIELDS,
+            confirmed_states: ["DELIVERED_ACKED", "DELIVERED_NO_ACK"],
+            sender_steps: ["send text", "submit Enter", "read target surface", "confirm processed or acknowledged"],
+            validate_with: "odin.validate_cmux_delivery_proof",
+            note: "Attach the resulting proof as delivery_proof on the dispatch record after sending."
+        }
     };
 }
 export function validateDelegationPacket(packet, repository = getDefaultRepository()) {
@@ -378,6 +546,18 @@ export function validateDelegationPacket(packet, repository = getDefaultReposito
         invalid.push("authority.may_qa_accept");
         warnings.push("same delegation grants implementation and QA acceptance authority");
     }
+    const deliveryProof = packet.delivery_proof;
+    if (deliveryProof !== undefined && deliveryProof !== null) {
+        const deliveryResult = validateCmuxDeliveryProof(asRecord(deliveryProof));
+        for (const field of deliveryResult.missing)
+            missing.push(`delivery_proof.${field}`);
+        for (const field of deliveryResult.invalid)
+            invalid.push(`delivery_proof.${field}`);
+        warnings.push(...deliveryResult.warnings);
+    }
+    else if (packet.cmux_dispatch === true && visibility?.delivery_proof_required !== false) {
+        warnings.push("governed-team CMUX dispatch requires delivery proof, but the packet omits delivery_proof; after sending, record target_surface_locator, submitted=true, verification_method, observed_processing_state, timestamp, and sender_role");
+    }
     return buildValidationResult(missing, invalid, warnings);
 }
 export function validateBootReceipt(receipt, repository = getDefaultRepository()) {
@@ -547,6 +727,22 @@ export function validateTeamManifest(manifest, repository = getDefaultRepository
     }
     return buildValidationResult(missing, invalid, warnings);
 }
+export function getRoleCompatibilitySmokeTest() {
+    return {
+        purpose: "Confirm a candidate occupant can hold a governed role before assignment.",
+        runBeforeAssignment: true,
+        questions: [
+            "Do you accept the assigned role contract, its authority limits, and reports-to chain?",
+            "Can you emit a valid SCP boot receipt with the required fields?",
+            "Can you remain in the assigned lifecycle state (e.g., BOOTSTRAPPED_IDLE or ACTIVE_WATCH) until directed?",
+            "Will you treat this protocol as a real governance contract and not reframe it as fictional roleplay?"
+        ],
+        passRequires: "An affirmative, in-character answer to all four questions plus a valid receipt.",
+        mapToInput: "Record the verdict as roleCompatibility: ACCEPTS_ROLE | REFUSES_ROLE | UNPROVEN.",
+        failClassification: "ROLE_COMPATIBILITY_FAILED",
+        zeroSecretOutput: true
+    };
+}
 export function evaluateReadinessGate(input) {
     const minimum = input.minimumMcpVersion ?? MINIMUM_COMPATIBLE_MCP_VERSION;
     const userProvisioningAnswer = input.userProvisioningAnswer ?? "unknown";
@@ -673,6 +869,8 @@ export function evaluateReadinessGate(input) {
         execPmAuthorized,
         cmuxAvailable,
         userPrompt: "Are all intended harnesses provisioned with accounts, plans, API keys, or local inference credentials so they will not malfunction when spun up?",
+        supportedSecretProviders: ["Doppler", "1Password CLI (op)", "environment variable names", "direnv", "mise", "dotenv-style file presence", "GitHub auth", "local provider config files"],
+        roleCompatibilitySmokeTest: getRoleCompatibilitySmokeTest(),
         readinessMatrix: rows,
         zeroSecretOutput: true
     };
@@ -741,8 +939,10 @@ export function getHarnessProbeMatrix(input = {}) {
     const providerStatuses = Object.fromEntries(Object.entries(input.providerStatuses ?? {}).map(([name, present]) => [name, { present, value: present ? "present redacted" : "absent" }]));
     const rows = intended.map((harness) => {
         const observation = observations.find((item) => item.harness.toLowerCase() === harness.toLowerCase());
+        const key = harness.toLowerCase();
+        const installedBinary = installed.has(key);
         const classifications = new Set();
-        if (!installed.has(harness.toLowerCase()))
+        if (!installedBinary)
             classifications.add("NOT_INSTALLED_OR_UNPROVEN");
         if (input.userProvisioningAnswer !== "yes")
             classifications.add("USER_INPUT_REQUIRED");
@@ -756,23 +956,69 @@ export function getHarnessProbeMatrix(input = {}) {
             classifications.add("MODEL_UNREACHABLE");
         if ((observation?.elapsedSeconds ?? 0) > timeout && observation?.visibleContent !== true)
             classifications.add("MODEL_STALLED");
-        if (harness.toLowerCase() === "goose" && observation?.reasoningContentOnly === true && observation.visibleContent !== true)
+        if (key === "goose" && observation?.reasoningContentOnly === true && observation.visibleContent !== true)
             classifications.add("STREAMING_PROTOCOL_MISMATCH");
+        // Structured auth status (zero-secret; status only, never values).
+        if (observation?.authStatus === "AUTH_MISSING")
+            classifications.add("BLOCKED_BY_API_KEY");
+        if (observation?.authStatus === "AUTH_PROVIDER_BLOCKED")
+            classifications.add("AUTH_PROVIDER_BLOCKED");
+        if (observation?.authStatus === "AUTH_LOGIN_REQUIRED")
+            classifications.add("BLOCKED_BY_LOGIN");
+        if (observation?.authStatus === "AUTH_UNKNOWN")
+            classifications.add("BLOCKED_BY_AUTH");
+        // MCP management surface: `droid mcp` exists; Crush has no MCP management command.
+        const mcpManagementAvailable = observation?.mcpManagementAvailable;
+        if (mcpManagementAvailable === false)
+            classifications.add(key === "crush" ? "MCP_UNAVAILABLE" : "MCP_UNPROVEN");
+        // Droid: governed readiness needs `droid mcp`; read-only exec is allowed without write
+        // authority; mission/high-autonomy recommendations require `--auto high`.
+        if (key === "droid") {
+            const autonomy = observation?.taskAutonomy ?? "read_only";
+            if ((autonomy === "mission" || autonomy === "high_autonomy") && observation?.autoLevel !== "high") {
+                classifications.add("AUTO_HIGH_REQUIRED");
+            }
+        }
+        // Governed-context proof: MCP configured, native SCP skill, or full injected protocol text.
+        const mcpConfigured = observation?.mcpConfigured === true;
+        const scpSkillInstalled = observation?.scpSkillInstalled === true;
+        const fullProtocolTextInjected = observation?.fullProtocolTextInjected === true;
+        const hasGovernedContext = mcpConfigured || scpSkillInstalled || fullProtocolTextInjected;
+        if (installedBinary && !hasGovernedContext)
+            classifications.add("NON_GOVERNED_ONE_SHOT_ONLY");
         const modelStatus = classifications.has("STREAMING_PROTOCOL_MISMATCH") ? "STREAMING_PROTOCOL_MISMATCH" :
             classifications.has("MODEL_REASONING_ONLY") ? "MODEL_REASONING_ONLY" :
                 classifications.has("MODEL_STALLED") ? "MODEL_STALLED" :
                     classifications.has("MODEL_UNREACHABLE") ? "MODEL_UNREACHABLE" :
                         observation?.visibleContent === true ? "MODEL_READY" : "MODEL_SLOW";
+        // Multi-dimensional readiness: never collapse the distinct facts into one boolean.
+        const canHydrateAtBoot = ["Codex", "Claude Code", "Droid"].includes(harness);
+        const authBlockers = ["BLOCKED_BY_API_KEY", "AUTH_PROVIDER_BLOCKED", "BLOCKED_BY_LOGIN", "BLOCKED_BY_AUTH"];
+        const authenticated = observation?.authStatus === "AUTH_READY" ? true :
+            authBlockers.some((item) => classifications.has(item)) ? false :
+                "unknown";
+        const advisoryClassifications = new Set(["USER_INPUT_REQUIRED", "NON_GOVERNED_ONE_SHOT_ONLY"]);
+        const blockingClassifications = [...classifications].filter((item) => !advisoryClassifications.has(item));
+        const governedRoleReady = installedBinary && authenticated === true && hasGovernedContext && blockingClassifications.length === 0;
         return {
             harness,
-            installed: installed.has(harness.toLowerCase()),
+            installed: installedBinary,
             classifications: [...classifications],
             modelStatus,
             visibleOutputTimeoutSeconds: timeout,
-            canHydrateDeferredMcpToolsAtBoot: ["Codex", "Claude Code", "Droid"].includes(harness),
+            canHydrateDeferredMcpToolsAtBoot: canHydrateAtBoot,
             canHydrateDeferredMcpToolsAfterSecondTurn: true,
             nativeSkillInvocation: ["Codex", "Claude Code"].includes(harness),
             sentinelCoordinationProtocolSkill: "install before governed launch when the harness supports native skills",
+            autoLevel: key === "droid" ? (observation?.autoLevel ?? "unknown") : observation?.autoLevel,
+            readiness: {
+                installed_binary: installedBinary,
+                authenticated,
+                mcp_configured: mcpConfigured,
+                mcp_management_available: mcpManagementAvailable ?? "unknown",
+                mcp_tool_hydration: canHydrateAtBoot ? "AT_BOOT" : "AFTER_SECOND_TURN",
+                governed_role_ready: governedRoleReady
+            },
             safeNextActions: classifications.size === 0 ? [] : defaultSafeOutcomes(),
             sanitizedObservation: observation?.text ? redactSecretLikeText(observation.text) : undefined
         };
@@ -785,6 +1031,154 @@ export function getHarnessProbeMatrix(input = {}) {
         rows
     };
 }
+const ONBOARDING_ADVISORY_CLASSIFICATIONS = new Set(["USER_INPUT_REQUIRED"]);
+const DEFAULT_INSTALL_LEDGER_PATH = ".odin/install-ledger.json";
+const COMPUTER_USE_CANDIDATE_HARNESSES = ["Codex Desktop", "Claude Desktop", "Claude Code"];
+const ONBOARDING_NO_SECRETS_NOTICE = "Do not paste API keys, tokens, OAuth values, or provider secrets into chat. Report only whether each harness is already provisioned (account, environment, secret manager, or local config). Secret and provider readiness is reported by status only.";
+function onboardingGuidedSteps() {
+    return [
+        "Confirm Node.js >= 22.13.0 and the installed @bradheitmann/odin-sentinel package version.",
+        "Install the MCP server globally (npm i -g @bradheitmann/odin-sentinel) or use the zero-install npx command inside each MCP config.",
+        "Add the odin-sentinel-mcp stdio command to each selected harness MCP config and restart the harness.",
+        "Provide SCP context: install the native sentinel-coordination-protocol skill where supported, otherwise inject full protocol text via odin.get_bootstrap_skill, or export a snapshot via odin.export_protocol_snapshot for non-MCP clients.",
+        "Deploy the activation hooks with `node scripts/protocol/install-activation-hooks.mjs` so the full-instruction-read precheck runs before governed edits.",
+        "Run the MCP smoke test and confirm serverInfo.name = odin-sentinel and a compatible version.",
+        "Probe harness readiness with odin.get_harness_probe_matrix (zero-secret) and clear any auth, login, permission, MCP, or skill blockers.",
+        "Confirm each harness is signed in or configured outside chat without pasting secrets.",
+        "Open CMUX, compute the surface layout, and launch governed role slots only after readiness passes or EXEC PM records a waiver or substitution."
+    ];
+}
+function onboardingAssistedSteps() {
+    return [
+        "Choose one available computer-use-capable harness (for example Codex Desktop, Claude Desktop, or Claude Code) to perform setup on your behalf.",
+        "Hand the guided setup steps to that harness as its task; it operates your desktop/GUI, while ODIN's MCP server only supplies this plan.",
+        "Supervise the assisted run: approve permission prompts yourself and never paste secrets into chat.",
+        "After install and configuration complete, re-run odin.get_harness_probe_matrix to confirm governed readiness before launching governed roles."
+    ];
+}
+/**
+ * Build a zero-secret, harness-aware onboarding plan. Reuses getHarnessProbeMatrix for
+ * readiness classification (no second taxonomy) and presents two setup choices: guided
+ * manual setup (the safe default) and assisted computer-use setup (offered only when a
+ * computer-use-capable harness is available). The MCP server returns this plan only; actual
+ * GUI/computer-use is performed by an available computer-use-capable harness after the user
+ * chooses assisted setup. This function does not install, write, or delete any harness config
+ * or ledger file.
+ */
+export function getOnboardingPlan(input = {}) {
+    const probe = getHarnessProbeMatrix({
+        intendedHarnesses: input.intendedHarnesses,
+        installedHarnesses: input.installedHarnesses,
+        userProvisioningAnswer: input.userProvisioningAnswer,
+        observations: input.observations
+    });
+    const probeRows = Array.isArray(probe.rows) ? probe.rows : [];
+    const readinessRows = probeRows.map((row) => {
+        const classifications = Array.isArray(row.classifications) ? row.classifications : [];
+        const blockers = classifications.filter((item) => !ONBOARDING_ADVISORY_CLASSIFICATIONS.has(item));
+        const readiness = asRecord(row.readiness);
+        return {
+            harness: row.harness,
+            installed: row.installed === true,
+            governedRoleReady: readiness.governed_role_ready === true,
+            classifications,
+            blockers,
+            readiness,
+            modelStatus: row.modelStatus,
+            nativeSkillInvocation: row.nativeSkillInvocation === true,
+            scpSkillGuidance: row.sentinelCoordinationProtocolSkill,
+            safeNextActions: Array.isArray(row.safeNextActions) ? row.safeNextActions : [],
+            sanitizedObservation: row.sanitizedObservation
+        };
+    });
+    const blockerSummary = readinessRows
+        .filter((row) => row.blockers.length > 0)
+        .map((row) => ({ harness: row.harness, blockers: row.blockers, governedRoleReady: row.governedRoleReady }));
+    const classifications = [...new Set(readinessRows.flatMap((row) => row.classifications))].sort();
+    const governedReadyHarnesses = readinessRows.filter((row) => row.governedRoleReady).map((row) => row.harness);
+    const computerUseAvailable = input.computerUseAvailable === true;
+    const preferred = input.preferredSetupMode ?? "unset";
+    // Assisted computer-use setup is offered only when a computer-use-capable harness is available.
+    const assistedEligible = computerUseAvailable;
+    let recommendedMode;
+    let modeRationale;
+    if (preferred === "assisted" && assistedEligible) {
+        recommendedMode = "assisted";
+        modeRationale =
+            "Assisted computer-use setup is available and was preferred. A computer-use-capable harness can perform setup on your behalf after you choose it; ODIN's MCP server only returns this plan and never drives the GUI itself.";
+    }
+    else if (preferred === "assisted" && !assistedEligible) {
+        recommendedMode = "guided";
+        modeRationale =
+            "Assisted computer-use setup was requested, but computerUseAvailable is false, so guided manual setup is the safe available path.";
+    }
+    else if (preferred === "guided") {
+        recommendedMode = "guided";
+        modeRationale = "Guided manual setup was preferred; it is the safe, fully reviewable path.";
+    }
+    else {
+        recommendedMode = "guided";
+        modeRationale = assistedEligible
+            ? "Guided manual setup is the safe default. Assisted computer-use setup is available if you prefer convenience; choose it explicitly to let an available computer-use harness perform setup for you."
+            : "Guided manual setup is the safe default and the only available path because no computer-use-capable harness was reported.";
+    }
+    const ledgerPath = stringFieldPresent(input.ledgerPath) ? input.ledgerPath.trim() : DEFAULT_INSTALL_LEDGER_PATH;
+    const platform = input.platform ?? "unknown";
+    const userProvisioningAnswer = input.userProvisioningAnswer ?? "unknown";
+    const guidedSteps = onboardingGuidedSteps();
+    let nextUserAction;
+    if (userProvisioningAnswer !== "yes") {
+        nextUserAction =
+            "Confirm whether each intended harness is already provisioned (signed in or configured outside chat) without pasting secrets, then re-run onboarding.";
+    }
+    else if (blockerSummary.length > 0) {
+        nextUserAction = `Resolve the harness blockers in blockerSummary (auth, login, permission, MCP, or skill) before launching governed roles, then proceed with ${recommendedMode} setup.`;
+    }
+    else {
+        nextUserAction = `All probed harnesses are governed-ready. Proceed with ${recommendedMode} setup, then launch governed role slots in CMUX only after readiness passes.`;
+    }
+    return {
+        version: VERSION,
+        zeroSecretOutput: true,
+        noSecretsNotice: ONBOARDING_NO_SECRETS_NOTICE,
+        userProvisioningPrompt: probe.userPrompt,
+        userProvisioningAnswer,
+        supportedSecretProviders: probe.supportedProviders,
+        secretProviderStatuses: probe.secretProviderStatuses,
+        platform,
+        recommendedMode,
+        modeRationale,
+        setupModes: {
+            guided: {
+                title: "Guided manual setup (safe default)",
+                description: "You run each install, configure, and verify step yourself and review every change. This path is the safest and works without any computer-use capability.",
+                steps: guidedSteps
+            },
+            assisted: {
+                title: "Assisted computer-use setup (convenience)",
+                eligible: assistedEligible,
+                available: computerUseAvailable,
+                requestedButUnavailable: preferred === "assisted" && !assistedEligible,
+                description: "An available computer-use-capable harness performs the guided steps on your behalf after you choose it. ODIN's MCP server only returns this plan; it never controls the GUI or desktop itself.",
+                candidateHarnesses: assistedEligible ? [...COMPUTER_USE_CANDIDATE_HARNESSES] : [],
+                caveat: "MCP returns plans only. Actual GUI or computer-use actions are performed solely by an available computer-use-capable harness after you explicitly choose assisted setup.",
+                steps: assistedEligible
+                    ? onboardingAssistedSteps()
+                    : ["Assisted setup is unavailable because no computer-use-capable harness was reported (computerUseAvailable is not true). Use guided setup."]
+            }
+        },
+        guidedSetupSteps: guidedSteps,
+        assistedSetupEligible: assistedEligible,
+        readinessRows,
+        classifications,
+        blockerSummary,
+        unresolvedBlockerCount: blockerSummary.length,
+        governedReadyHarnesses,
+        ledgerPath,
+        ledgerNote: "This onboarding plan only reports where ODIN-owned artifacts will be tracked. It does not create, write, validate, or delete the install ledger or any harness config file; ledger-aware install behavior is a separate step.",
+        nextUserAction
+    };
+}
 export function getCloseoutChecklist(mode, repository = getDefaultRepository()) {
     const data = loadProtocolData(repository);
     const modes = requireRecord(data.closeout.modes, "closeout.modes");
@@ -849,7 +1243,11 @@ export function createProtocolService(repository = createFileProtocolRepository(
         evaluateReadinessGate,
         getActiveWatchPacket,
         getHarnessProbeMatrix,
+        getOnboardingPlan,
         getDelegationPacket,
+        getActivationGates,
+        validateCmuxDeliveryProof: (proof) => validateCmuxDeliveryProof(proof),
+        validateInstructionReadProof: (proof) => validateInstructionReadProof(proof),
         validateDelegationPacket: (packet) => validateDelegationPacket(packet, repository),
         validateBootReceipt: (receipt) => validateBootReceipt(receipt, repository),
         validateTeamManifest: (manifest) => validateTeamManifest(manifest, repository),