@haaaiawd/second-nature 0.2.9 → 0.2.13

package/index.js

@@ -31,6 +31,12 @@
  *   illusion of a working plugin while agent sessions see no tool. We hit
  *   exactly that on 2026-05-06; the fix lives in plugin/openclaw.plugin.json
  *   under the `activation` block.
+ * - Cloud Feishu/OpenClaw sessions can report `capabilities=none`. In that
+ *   mode, binding activation to `onCapabilities:["tool"]` prevents the agent
+ *   tool from entering the session even though the plugin loaded. Therefore
+ *   the manifest keeps `activation.onStartup === true` for daemon loading and
+ *   declares the tool through `contracts.tools`, but does not require a session
+ *   capability to activate `second_nature_ops`.
  * - `Shape: non-capability` reported by `openclaw plugins info` is EXPECTED
  *   for this plugin. OpenClaw counts capabilities only across cli-backend /
  *   text-inference / speech / realtime-* / media-understanding /
@@ -45,7 +51,7 @@
  * **same absolute path** as the OpenClaw **agent workspace** (default `~/.openclaw/workspace`, or
  * `agents.defaults.workspace` in `~/.openclaw/openclaw.json`). Do **not** infer that root from the plugin
  * install directory. With **sandbox** or **per-agent workspaces**, use the path where `data/state.db` and
- * `workspace/` anchors actually live. See `explore/reports/2026-05-04_openclaw-plugin-install-vs-workspace-root.md`.
+ * `workspace/` anchors actually live.
  *
  * Test coverage:
  * - tests/integration/cli/plugin-runtime-registration.test.ts
@@ -75,6 +81,20 @@ const HOST_SAFE_LIMITATION_MESSAGE = "Host-safe plugin package keeps synchronous
 const SETUP_MARKER_RELATIVE_PATH = path.join(".second-nature", "setup", "agent-inner-guide-ack.json");
 const SETUP_GUIDE_VERSION = "0.1.38";
 const SETUP_COMMANDS = new Set(["setup_hint", "setup_ack"]);
+// T-SH.R.8: Import shared setup-ack validator instead of duplicating.
+// Source of truth: src/shared/setup-ack.ts (copied to plugin/runtime/shared/ by build).
+import { validateSetupAck as validateSetupAckShared, SETUP_ACK_SCHEMA_VERSION, } from "./runtime/shared/setup-ack.js";
+/**
+ * Wrapper that adapts the shared validator's richer return type
+ * ({ok:true, ack} | {ok:false, errors}) to the plugin's historical
+ * ({ok:true} | {ok:false, errors}) shape. Keeps call sites unchanged.
+ */
+function validateSetupAck(raw) {
+    const result = validateSetupAckShared(raw);
+    if (result.ok)
+        return { ok: true };
+    return { ok: false, errors: result.errors };
+}
 let activationSpine = null;
 /** T1.1.4 — lazily opened full read bridge; closed when workspace root / resolution changes. */
 let workspaceOpsBridge = null;
@@ -242,6 +262,31 @@ function safeShortText(value, maxLength = 240) {
         ? `${trimmed.slice(0, maxLength - 3)}...`
         : trimmed;
 }
+function buildHostDiscoveryReport(input) {
+    const observedAt = new Date().toISOString();
+    const hostName = typeof input?.hostName === "string" ? input.hostName : undefined;
+    const hostVersion = typeof input?.hostVersion === "string" ? input.hostVersion : undefined;
+    return {
+        toolDiscovery: {
+            status: "unsupported",
+            tools: [],
+            hostName,
+            hostVersion,
+            observedAt,
+            reason: "host_probe_unsupported",
+        },
+        skillDiscovery: {
+            status: "unsupported",
+            skills: [],
+            observedAt,
+            reason: "skill_probe_unsupported",
+        },
+        setupComplete: false,
+        evidenceLevel: "carrier_ack",
+        reason: "host_probe_unsupported",
+        nextStep: "host_safe_carrier_cannot_probe_host_registry_run_workspace_cli_for_full_discovery",
+    };
+}
 function resolveSetupMarkerPath(spine) {
     if (spine.workspaceRootContext.resolution === "unknown") {
         return undefined;
@@ -258,6 +303,16 @@ function readSetupAckMarker(spine) {
     }
     try {
         const marker = JSON.parse(fs.readFileSync(markerPath, "utf-8"));
+        const validation = validateSetupAck(marker);
+        if (!validation.ok) {
+            return {
+                status: "incomplete",
+                markerPath,
+                acknowledgedAt: marker.acknowledgedAt,
+                placedIn: marker.placedIn,
+                incompleteReasons: validation.errors,
+            };
+        }
         return {
             status: "acknowledged",
             markerPath,
@@ -266,7 +321,17 @@ function readSetupAckMarker(spine) {
         };
     }
     catch {
-        return { status: "pending", markerPath };
+        return {
+            status: "incomplete",
+            markerPath,
+            incompleteReasons: [
+                {
+                    field: "marker",
+                    reason: "Marker file is not valid JSON",
+                    repairAction: "Re-run setup_ack to rewrite the marker with a valid schema.",
+                },
+            ],
+        };
     }
 }
 function readPackagedSetupText(fileName) {
@@ -321,20 +386,27 @@ function buildSetupHintPayload(spine, input) {
     const includeSkill = input?.includeSkill !== false;
     const includeGuide = input?.includeGuide !== false;
     const ack = readSetupAckMarker(spine);
+    const hostDiscovery = buildHostDiscoveryReport(input);
     const data = {
         status: ack.status,
         workspaceRootResolution: spine.workspaceRootContext.resolution,
         markerPath: ack.markerPath,
         acknowledgedAt: ack.acknowledgedAt,
         placedIn: ack.placedIn,
+        hostDiscovery,
         recommendedPlacement: [
             "agent prompt",
             "workspace/IDENTITY.md",
             "workspace/USER.md",
         ],
         nextStep: ack.status === "acknowledged"
-            ? "setup_already_acknowledged"
-            : "read_returned_guidance_then_run_setup_ack",
+            ? hostDiscovery.setupComplete
+                ? "setup_verified_by_host_discovery"
+                : hostDiscovery.nextStep
+            : ack.status === "incomplete"
+                ? "repair_setup_ack_fields"
+                : "read_returned_guidance_then_run_setup_ack",
+        ...(ack.incompleteReasons ? { incompleteReasons: ack.incompleteReasons } : {}),
     };
     if (includeSkill) {
         const skill = readPackagedSetupText("SKILL.md");
@@ -358,6 +430,7 @@ function buildSetupHintPayload(spine, input) {
         ok: true,
         command: "setup_hint",
         surfaceMode: "host_safe_carrier",
+        evidenceLevel: "contract_smoke",
         message: "Read the SKILL and guide as a friendly setup note, then place the guidance where the agent naturally checks its working anchors.",
         data,
     };
@@ -376,25 +449,48 @@ function buildSetupAckPayload(spine, input) {
             },
         };
     }
+    const placedIn = safeShortText(input?.placedIn, 160);
+    const placementProofRef = safeShortText(input?.placementProofRef, 320);
+    const writer = safeShortText(input?.writer, 80);
     const marker = {
+        schemaVersion: SETUP_ACK_SCHEMA_VERSION,
         acknowledgedAt: new Date().toISOString(),
         acceptedBy: safeShortText(input?.acceptedBy, 80) ?? "agent",
-        placedIn: safeShortText(input?.placedIn, 160) ?? "unspecified",
+        placedIn: placedIn ?? "unspecified",
+        placementProofRef: placementProofRef ?? "",
         note: safeShortText(input?.note, 240),
         guideVersion: SETUP_GUIDE_VERSION,
         source: "second-nature-plugin",
         skillPath: "SKILL.md",
         guidePath: "agent-inner-guide.md",
+        writer: writer ?? "setup_ack_command",
     };
+    const validation = validateSetupAck(marker);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            command: "setup_ack",
+            surfaceMode: "host_safe_carrier",
+            evidenceLevel: "carrier_ack",
+            message: "Setup acknowledgement is incomplete; see incompleteReasons and repairAction.",
+            data: {
+                markerPath,
+                incompleteReasons: validation.errors,
+            },
+        };
+    }
     fs.mkdirSync(path.dirname(markerPath), { recursive: true });
     fs.writeFileSync(markerPath, `${JSON.stringify(marker, null, 2)}\n`, "utf-8");
+    const hostDiscovery = buildHostDiscoveryReport(input);
     return {
         ok: true,
         command: "setup_ack",
         surfaceMode: "host_safe_carrier",
-        message: "Setup guide acknowledgement persisted; setup nudge is now silent for this workspace.",
+        evidenceLevel: hostDiscovery.evidenceLevel,
+        message: "Setup guide acknowledgement persisted; setup nudge is now silent for this workspace. Host skill discovery is unavailable in carrier mode.",
         data: {
             markerPath,
+            hostDiscovery,
             ...marker,
         },
     };

package/openclaw.plugin.json

@@ -1,13 +1,10 @@
 {
   "id": "second-nature",
   "name": "Second Nature",
-  "version": "0.2.9",
+  "version": "0.2.13",
   "description": "OpenClaw native plugin with synchronous surface registration and bundled runtime spine. Set SECOND_NATURE_WORKSPACE_ROOT or tool workspaceRoot to the same path as the agent workspace. Agent inner guide is packaged as agent-inner-guide.md. Ops surface: loop_status, self_health, tool_affordance, heartbeat_check, heartbeat_run, heartbeat_digest, snapshot:capture, narrative:diff, timeline, restore, runtime_secret_bootstrap, connector:run, guidance_payload.",
   "activation": {
-    "onStartup": true,
-    "onCapabilities": [
-      "tool"
-    ]
+    "onStartup": true
   },
   "contracts": {
     "commands": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haaaiawd/second-nature",
-  "version": "0.2.9",
+  "version": "0.2.13",
   "description": "OpenClaw native plugin with synchronous registration, a packaged runtime artifact, and operator-facing status/explain flows.",
   "keywords": [
     "openclaw",

package/runtime/cli/commands/index.js

@@ -7,6 +7,8 @@ import { explainSurfaceSubject } from "../explain/explain-surface-subject.js";
 import { showOperatorFallback, OperatorFallbackNotFoundError, } from "../ops/show-operator-fallback.js";
 import { runStorageModeSmoke } from "../../storage/bootstrap/storage-mode-smoke.js";
 import { policySet } from "./policy.js";
+import { validateSetupAck, SETUP_ACK_SCHEMA_VERSION } from "../../shared/setup-ack.js";
+import { createDefaultHostDiscoveryPort, probeHostDiscovery, recordHostToolVisibilityLog, } from "../host-capability/host-discovery-port.js";
 const SETUP_MARKER_RELATIVE_PATH = path.join(".second-nature", "setup", "agent-inner-guide-ack.json");
 function safeShortText(value, maxLen) {
     if (typeof value !== "string")
@@ -53,11 +55,21 @@ function readSetupAckMarker(workspaceRoot) {
         const raw = fs.readFileSync(markerPath, "utf-8");
         const marker = JSON.parse(raw);
         if (marker.status === "acknowledged") {
+            const validation = validateSetupAck(marker);
+            if (validation.ok) {
+                return {
+                    status: "acknowledged",
+                    markerPath,
+                    acknowledgedAt: validation.ack.acknowledgedAt,
+                    placedIn: validation.ack.placedIn,
+                };
+            }
             return {
-                status: "acknowledged",
+                status: "incomplete",
                 markerPath,
                 acknowledgedAt: typeof marker.acknowledgedAt === "string" ? marker.acknowledgedAt : undefined,
                 placedIn: typeof marker.placedIn === "string" ? marker.placedIn : undefined,
+                incompleteReasons: validation.errors,
             };
         }
     }
@@ -72,20 +84,32 @@ async function buildSetupHintPayload(input) {
     const includeGuide = input?.includeGuide !== false;
     const workspaceRoot = resolveWorkspaceRoot(input);
     const ack = readSetupAckMarker(workspaceRoot);
+    const hostDiscovery = await probeHostDiscovery({
+        port: createDefaultHostDiscoveryPort(),
+        hostName: typeof input?.hostName === "string" ? input.hostName : undefined,
+        hostVersion: typeof input?.hostVersion === "string" ? input.hostVersion : undefined,
+    });
+    await recordHostToolVisibilityLog(workspaceRoot, "setup_hint", hostDiscovery);
     const data = {
         status: ack.status,
         workspaceRoot,
         markerPath: ack.markerPath,
         acknowledgedAt: ack.acknowledgedAt,
         placedIn: ack.placedIn,
+        hostDiscovery,
         recommendedPlacement: [
             "agent prompt",
             "workspace/IDENTITY.md",
             "workspace/USER.md",
         ],
         nextStep: ack.status === "acknowledged"
-            ? "setup_already_acknowledged"
-            : "read_returned_guidance_then_run_setup_ack",
+            ? hostDiscovery.setupComplete
+                ? "setup_verified_by_host_discovery"
+                : hostDiscovery.nextStep
+            : ack.status === "incomplete"
+                ? "repair_setup_ack_fields"
+                : "read_returned_guidance_then_run_setup_ack",
+        ...(ack.incompleteReasons ? { incompleteReasons: ack.incompleteReasons } : {}),
     };
     if (includeSkill) {
         const skill = readSetupText("SKILL.md");
@@ -108,35 +132,76 @@ async function buildSetupHintPayload(input) {
     return {
         ok: true,
         command: "setup_hint",
+        runtimeMode: "workspace_full_runtime",
         surfaceMode: "workspace_full_runtime",
-        message: "Read the SKILL and guide as a friendly setup note, then place the guidance where the agent naturally checks its working anchors.",
-        data,
+        generatedAt: new Date().toISOString(),
+        evidenceLevel: "contract_smoke",
+        warnings: [],
+        sourceRefs: [],
+        data: {
+            message: "Read the SKILL and guide as a friendly setup note, then place the guidance where the agent naturally checks its working anchors.",
+            ...data,
+        },
     };
 }
 async function buildSetupAckPayload(input) {
     const workspaceRoot = resolveWorkspaceRoot(input);
     const markerPath = path.join(workspaceRoot, SETUP_MARKER_RELATIVE_PATH);
-    const marker = {
+    const placedIn = safeShortText(input?.placedIn, 160);
+    const placementProofRef = safeShortText(input?.placementProofRef, 320);
+    const writer = safeShortText(input?.writer, 80);
+    const candidate = {
+        schemaVersion: SETUP_ACK_SCHEMA_VERSION,
         acknowledgedAt: new Date().toISOString(),
         acceptedBy: safeShortText(input?.acceptedBy, 80) ?? "agent",
-        placedIn: safeShortText(input?.placedIn, 160) ?? "unspecified",
+        placedIn: placedIn ?? "unspecified",
+        placementProofRef: placementProofRef ?? "",
         note: safeShortText(input?.note, 240),
         guideVersion: "0.2.5",
+        writer: writer ?? "setup_ack_command",
         source: "second-nature-cli",
         skillPath: "SKILL.md",
         guidePath: "plugin/agent-inner-guide.md",
         status: "acknowledged",
     };
+    const validation = validateSetupAck(candidate);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            command: "setup_ack",
+            surfaceMode: "workspace_full_runtime",
+            evidenceLevel: "carrier_ack",
+            message: "Setup acknowledgement is incomplete; see errors and repairAction.",
+            data: {
+                markerPath,
+                validationErrors: validation.errors,
+            },
+        };
+    }
     fs.mkdirSync(path.dirname(markerPath), { recursive: true });
-    fs.writeFileSync(markerPath, `${JSON.stringify(marker, null, 2)}\n`, "utf-8");
+    fs.writeFileSync(markerPath, `${JSON.stringify(candidate, null, 2)}\n`, "utf-8");
+    const hostDiscovery = await probeHostDiscovery({
+        port: createDefaultHostDiscoveryPort(),
+        hostName: typeof input?.hostName === "string" ? input.hostName : undefined,
+        hostVersion: typeof input?.hostVersion === "string" ? input.hostVersion : undefined,
+    });
+    await recordHostToolVisibilityLog(workspaceRoot, "setup_ack", hostDiscovery);
     return {
         ok: true,
         command: "setup_ack",
+        runtimeMode: "workspace_full_runtime",
         surfaceMode: "workspace_full_runtime",
-        message: "Setup guide acknowledgement persisted; setup nudge is now silent for this workspace.",
+        generatedAt: new Date().toISOString(),
+        evidenceLevel: hostDiscovery.setupComplete ? "state_present" : "carrier_ack",
+        warnings: hostDiscovery.setupComplete ? [] : ["host_discovery_incomplete"],
+        sourceRefs: [],
         data: {
+            message: hostDiscovery.setupComplete
+                ? "Setup guide acknowledgement persisted and host discovery confirms tool/skill visibility."
+                : "Setup guide acknowledgement persisted, but host discovery has not confirmed tool/skill visibility; see hostDiscovery.",
             markerPath,
-            ...marker,
+            hostDiscovery,
+            ...candidate,
         },
     };
 }
@@ -322,7 +387,16 @@ export function createCliCommands(deps) {
         },
         {
             name: "heartbeat_check",
-            description: "Workspace heartbeat_check ops surface (v5 HeartbeatSurfaceResult)",
+            description: "v8 living-loop heartbeat — runs real-runtime perception/judgment/action closure",
+            execute: async (input) => {
+                const surface = await Promise.resolve(opsRouter.dispatch("heartbeat_check", input));
+                flush();
+                return surface;
+            },
+        },
+        {
+            name: "heartbeat",
+            description: "[DEPRECATED] v7 heartbeat entrypoint; alias to heartbeat_check",
             execute: async (input) => {
                 const surface = await Promise.resolve(opsRouter.dispatch("heartbeat_check", input));
                 flush();

package/runtime/cli/host-capability/host-discovery-port.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Host Capability Discovery Port (T-ROS.R.7, T-ROS.R.9)
+ *
+ * Core logic: provide an explicit boundary for proving that the Second Nature
+ * tool (`second_nature_ops`) and packaged skill are visible to the host.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/runtime-ops-system.md §3.1`
+ *
+ * Dependencies: none (plain contracts)
+ * Boundary: pure interface + a default fail-closed adapter that reports
+ * `host_probe_unsupported` rather than inventing a discovery proof.
+ *
+ * T-ROS.R.9 manual-smoke-only contract (option b):
+ * In carrier/packaged mode, there is no OpenClaw host API available for
+ * introspection. The default adapter returns `unsupported` with
+ * `host_probe_unsupported` reason. The positive path (T-ROS.R.5
+ * "host-visible second_nature_ops") is borne by external manual host smoke.
+ * `05B_VERIFICATION_PLAN.md` marks T-ROS.R.5 as "requires manual host evidence"
+ * with required fields: hostName, hostVersion, timestamp, raw tool list JSON.
+ * Callers must not promote `evidenceLevel` beyond `carrier_ack` without
+ * a real `HostCapabilityDiscoveryPort` implementation or manual smoke proof.
+ *
+ * Test coverage: tests/unit/cli/host-discovery-port.test.ts
+ */
+export type HostDiscoveryStatus = "available" | "unavailable" | "unsupported" | "blocked";
+export type HostToolUnavailableReason = "host_tool_unavailable" | "host_probe_unsupported" | "host_policy_blocked" | "host_probe_timeout";
+export type HostSkillUnavailableReason = "skill_projection_unavailable" | "skill_probe_unsupported" | "host_policy_blocked" | "host_probe_timeout";
+export interface HostToolDiscoveryResult {
+    status: HostDiscoveryStatus;
+    tools: string[];
+    hostName?: string;
+    hostVersion?: string;
+    observedAt: string;
+    reason?: HostToolUnavailableReason;
+}
+export interface HostSkillDiscoveryResult {
+    status: HostDiscoveryStatus;
+    skills: string[];
+    observedAt: string;
+    reason?: HostSkillUnavailableReason;
+}
+export interface HostCapabilityDiscoveryPort {
+    /** Prove that `second_nature_ops` is visible in the current host session. */
+    listHostTools(): Promise<HostToolDiscoveryResult>;
+    /** Prove that the packaged skill is discoverable by the host skill registry. */
+    listHostSkills?(): Promise<HostSkillDiscoveryResult>;
+}
+export interface HostDiscoveryProbeOptions {
+    port: HostCapabilityDiscoveryPort;
+    hostName?: string;
+    hostVersion?: string;
+}
+export interface HostDiscoveryReport {
+    toolDiscovery: HostToolDiscoveryResult;
+    skillDiscovery: HostSkillDiscoveryResult;
+    setupComplete: boolean;
+    /** Evidence level for setup state after applying discovery truth. */
+    evidenceLevel: "carrier_ack" | "contract_smoke" | "state_present";
+    reason?: HostToolUnavailableReason | HostSkillUnavailableReason;
+    nextStep: string;
+}
+/**
+ * Default fail-closed adapter. It does not invent host API access;
+ * it returns explicit `unsupported` diagnostics so callers cannot
+ * promote setup to `real_runtime` without real host evidence.
+ */
+export declare function createDefaultHostDiscoveryPort(): HostCapabilityDiscoveryPort;
+export declare function probeHostDiscovery(options: HostDiscoveryProbeOptions): Promise<HostDiscoveryReport>;
+export interface HostToolVisibilityLogEntry {
+    observedAt: string;
+    hostName?: string;
+    hostVersion?: string;
+    command: string;
+    toolDiscovery: HostToolDiscoveryResult;
+    skillDiscovery: HostSkillDiscoveryResult;
+    evidenceLevel: HostDiscoveryReport["evidenceLevel"];
+    setupComplete: boolean;
+}
+/**
+ * Persist a host tool/skill visibility log under the workspace so manual host
+ * smoke appendices can include timestamp, hostName, hostVersion, raw tool list,
+ * command envelope, and evidenceLevel.
+ */
+export declare function recordHostToolVisibilityLog(workspaceRoot: string, command: string, report: HostDiscoveryReport): Promise<void>;

package/runtime/cli/host-capability/host-discovery-port.js

@@ -0,0 +1,137 @@
+/**
+ * Host Capability Discovery Port (T-ROS.R.7, T-ROS.R.9)
+ *
+ * Core logic: provide an explicit boundary for proving that the Second Nature
+ * tool (`second_nature_ops`) and packaged skill are visible to the host.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/runtime-ops-system.md §3.1`
+ *
+ * Dependencies: none (plain contracts)
+ * Boundary: pure interface + a default fail-closed adapter that reports
+ * `host_probe_unsupported` rather than inventing a discovery proof.
+ *
+ * T-ROS.R.9 manual-smoke-only contract (option b):
+ * In carrier/packaged mode, there is no OpenClaw host API available for
+ * introspection. The default adapter returns `unsupported` with
+ * `host_probe_unsupported` reason. The positive path (T-ROS.R.5
+ * "host-visible second_nature_ops") is borne by external manual host smoke.
+ * `05B_VERIFICATION_PLAN.md` marks T-ROS.R.5 as "requires manual host evidence"
+ * with required fields: hostName, hostVersion, timestamp, raw tool list JSON.
+ * Callers must not promote `evidenceLevel` beyond `carrier_ack` without
+ * a real `HostCapabilityDiscoveryPort` implementation or manual smoke proof.
+ *
+ * Test coverage: tests/unit/cli/host-discovery-port.test.ts
+ */
+import fs from "node:fs";
+import path from "node:path";
+const SECOND_NATURE_SKILL_ID = "second-nature";
+const SECOND_NATURE_OPS_TOOL = "second_nature_ops";
+/**
+ * Default fail-closed adapter. It does not invent host API access;
+ * it returns explicit `unsupported` diagnostics so callers cannot
+ * promote setup to `real_runtime` without real host evidence.
+ */
+export function createDefaultHostDiscoveryPort() {
+    return {
+        async listHostTools() {
+            return {
+                status: "unsupported",
+                tools: [],
+                observedAt: new Date().toISOString(),
+                reason: "host_probe_unsupported",
+            };
+        },
+        async listHostSkills() {
+            return {
+                status: "unsupported",
+                skills: [],
+                observedAt: new Date().toISOString(),
+                reason: "skill_probe_unsupported",
+            };
+        },
+    };
+}
+function capSetupEvidenceLevel(toolStatus, skillStatus) {
+    if (toolStatus !== "available" || skillStatus !== "available") {
+        return "carrier_ack";
+    }
+    return "state_present";
+}
+export async function probeHostDiscovery(options) {
+    const { port, hostName, hostVersion } = options;
+    const toolDiscovery = await port.listHostTools();
+    const skillDiscovery = port.listHostSkills
+        ? await port.listHostSkills()
+        : {
+            status: "unsupported",
+            skills: [],
+            observedAt: new Date().toISOString(),
+            reason: "skill_probe_unsupported",
+        };
+    const toolOk = toolDiscovery.status === "available" &&
+        toolDiscovery.tools.includes(SECOND_NATURE_OPS_TOOL);
+    const skillOk = skillDiscovery.status === "available" &&
+        skillDiscovery.skills.includes(SECOND_NATURE_SKILL_ID);
+    const setupComplete = toolOk && skillOk;
+    const evidenceLevel = capSetupEvidenceLevel(toolDiscovery.status, skillDiscovery.status);
+    let reason;
+    let nextStep;
+    if (!toolOk) {
+        reason = toolDiscovery.reason ?? "host_tool_unavailable";
+        nextStep =
+            "confirm_second_nature_ops_is_enabled_in_host_tool_registry_and_re_run_setup_hint";
+    }
+    else if (!skillOk) {
+        reason = skillDiscovery.reason ?? "skill_projection_unavailable";
+        nextStep =
+            "confirm_packaged_SKILL.md_is_indexed_by_host_skill_registry_and_re_run_setup_hint";
+    }
+    else {
+        nextStep = "setup_verified_by_host_discovery";
+    }
+    return {
+        toolDiscovery: {
+            ...toolDiscovery,
+            hostName,
+            hostVersion,
+        },
+        skillDiscovery,
+        setupComplete,
+        evidenceLevel,
+        reason,
+        nextStep,
+    };
+}
+/**
+ * Persist a host tool/skill visibility log under the workspace so manual host
+ * smoke appendices can include timestamp, hostName, hostVersion, raw tool list,
+ * command envelope, and evidenceLevel.
+ */
+export async function recordHostToolVisibilityLog(workspaceRoot, command, report) {
+    const logDir = path.join(workspaceRoot, ".second-nature", "logs");
+    fs.mkdirSync(logDir, { recursive: true });
+    const logPath = path.join(logDir, "host-tool-visibility.json");
+    const entry = {
+        observedAt: new Date().toISOString(),
+        hostName: report.toolDiscovery.hostName,
+        hostVersion: report.toolDiscovery.hostVersion,
+        command,
+        toolDiscovery: report.toolDiscovery,
+        skillDiscovery: report.skillDiscovery,
+        evidenceLevel: report.evidenceLevel,
+        setupComplete: report.setupComplete,
+    };
+    let existing = [];
+    try {
+        const raw = fs.readFileSync(logPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed))
+            existing = parsed;
+    }
+    catch {
+        // File missing or unreadable — start fresh.
+    }
+    existing.push(entry);
+    fs.writeFileSync(logPath, `${JSON.stringify(existing.slice(-50), null, 2)}\n`, "utf-8");
+}

package/runtime/cli/host-capability/probe-host-capability.js

@@ -7,7 +7,7 @@ function mergeEvidenceRefs(...groups) {
     const out = [];
     for (const group of groups) {
         for (const ref of group) {
-            const key = `${ref.kind}:${ref.id}`;
+            const key = `${ref.family}:${ref.id}`;
             if (!seen.has(key)) {
                 seen.add(key);
                 out.push(ref);

package/runtime/cli/host-capability/types.d.ts

@@ -3,15 +3,10 @@
  *
  * Test coverage: tests/unit/cli/host-capability.test.ts, tests/integration/cli/host-capability-probe.test.ts
  */
+import type { SourceRef } from "../../shared/types/v8-contracts.js";
+export type { SourceRef } from "../../shared/types/v8-contracts.js";
 export type DeliveryCapabilityStatus = "target_available" | "target_none" | "channel_missing" | "host_api_unavailable" | "host_unsupported" | "unknown";
 export type CapabilityVerdict = "pass" | "fail" | "unknown" | "not_applicable";
-export interface SourceRef {
-    id: string;
-    kind: "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
-    uri: string;
-    excerptHash?: string;
-    observedAt?: string;
-}
 export interface HostCapabilityDocReference {
     title: string;
     url: string;

package/runtime/cli/host-capability/types.js

@@ -1,6 +1 @@
-/**
- * Host capability probe contracts (cli-system v5 / ADR-007).
- *
- * Test coverage: tests/unit/cli/host-capability.test.ts, tests/integration/cli/host-capability-probe.test.ts
- */
 export {};