fullcourtdefense-cli 1.26.17 → 1.27.0

package/dist/actionPolicyEngine.d.ts

@@ -59,10 +59,26 @@ export interface ActionPolicyRule {
     /** Approval routing for `require_approval` rules. Absent = org admin approval, no memory, block on timeout. */
     approval?: ActionPolicyApproval;
 }
+/**
+ * The three kinds of machine a fleet policy can be written for:
+ *   - `workstation` — laptops / desktops a person uses (default for any machine that does not say otherwise)
+ *   - `ci`          — ephemeral CI runner VMs enrolled with `ci-protect` (one row per pipeline)
+ *   - `workload`    — containers, pods, jobs, functions enrolled with `workload-protect`
+ * A call that carries no `machineKind` in its context is treated as a workstation, so a
+ * policy written only for containers can never fire on a laptop (and vice versa).
+ */
+export type MachineKind = 'workstation' | 'ci' | 'workload';
+export declare const MACHINE_KINDS: readonly MachineKind[];
 export interface ActionPolicyTargeting {
     developerNames?: string[];
     machineNames?: string[];
+    /** Restrict to these machine kinds. Empty/absent = every kind (a GLOBAL policy). */
+    machineKinds?: MachineKind[];
 }
+/** Normalize a context value into a MachineKind; anything unknown is a workstation. */
+export declare function normalizeMachineKind(value: string | undefined): MachineKind;
+/** Does this policy's kind targeting include the given machine kind? Empty targeting = yes. */
+export declare function policyTargetsMachineKind(appliesTo: ActionPolicyTargeting | undefined, kind: MachineKind): boolean;
 /** The minimal policy shape the engine needs — structurally satisfied by the backend's ActionPolicy. */
 export interface EngineActionPolicy {
     id: string;

package/dist/actionPolicyEngine.js

@@ -18,7 +18,9 @@
  * they diverge. Change this file? Copy it to the other location verbatim.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_ACTION_POLICY_APPROVAL = void 0;
+exports.DEFAULT_ACTION_POLICY_APPROVAL = exports.MACHINE_KINDS = void 0;
+exports.normalizeMachineKind = normalizeMachineKind;
+exports.policyTargetsMachineKind = policyTargetsMachineKind;
 exports.resolveApprovalOptions = resolveApprovalOptions;
 exports.effectiveApprovalScope = effectiveApprovalScope;
 exports.deriveToolOperations = deriveToolOperations;
@@ -26,6 +28,17 @@ exports.toolCapabilities = toolCapabilities;
 exports.evaluateActionPolicies = evaluateActionPolicies;
 exports.inferToolContext = inferToolContext;
 exports.inventoryToolMatchesActionPolicy = inventoryToolMatchesActionPolicy;
+exports.MACHINE_KINDS = ['workstation', 'ci', 'workload'];
+/** Normalize a context value into a MachineKind; anything unknown is a workstation. */
+function normalizeMachineKind(value) {
+    const kind = (value || '').trim().toLowerCase();
+    return kind === 'ci' || kind === 'workload' ? kind : 'workstation';
+}
+/** Does this policy's kind targeting include the given machine kind? Empty targeting = yes. */
+function policyTargetsMachineKind(appliesTo, kind) {
+    const kinds = (appliesTo?.machineKinds || []).filter(Boolean);
+    return kinds.length === 0 || kinds.includes(kind);
+}
 exports.DEFAULT_ACTION_POLICY_APPROVAL = {
     scope: 'org',
     remember: 'none',
@@ -408,7 +421,7 @@ const OPERATION_MATCH_SKIP_FIELDS = new Set([
     'tool.status', 'operation.status', 'agent.baseline',
     // Identity / metadata — NOT action signals. Excluded so the tool/agent name can never
     // pollute operation matching.
-    'toolName', 'agentName', 'developerName', 'machineName', 'ipAddress', 'agentClient', 'gateway', 'mcpServer', 'environment',
+    'toolName', 'agentName', 'developerName', 'machineName', 'machineKind', 'ipAddress', 'agentClient', 'gateway', 'mcpServer', 'environment',
     // Document / file CONTENT — data being written or displayed, not the action itself.
     // A file whose text mentions "delete" or "npm publish" is not a delete or a deploy;
     // matching rule verbs against document bodies pauses ordinary file edits (real incident:
@@ -484,11 +497,14 @@ function isInternalHost(hostname) {
     return Boolean(private172 && Number(private172[1]) >= 16 && Number(private172[1]) <= 31);
 }
 /**
- * First-class policy targeting (appliesTo.developerNames / machineNames).
+ * First-class policy targeting (appliesTo.developerNames / machineNames / machineKinds).
  * Empty targeting = applies to everyone. A targeted policy only applies when the call
- * carries the matching identity context (case-insensitive exact match).
+ * carries the matching identity context (case-insensitive exact match). Kind targeting
+ * reads `context.machineKind` (workstation when absent).
  */
 function policyTargetsCall(policy, context) {
+    if (!policyTargetsMachineKind(policy.appliesTo, normalizeMachineKind(context.machineKind)))
+        return false;
     const developerTargets = policy.appliesTo?.developerNames?.filter(Boolean) || [];
     const machineTargets = policy.appliesTo?.machineNames?.filter(Boolean) || [];
     if (developerTargets.length > 0) {

package/dist/commands/ciProtect.js

@@ -5,6 +5,7 @@ exports.ciProtectCommand = ciProtectCommand;
 const config_1 = require("../config");
 const cliVersion_1 = require("../cliVersion");
 const ephemeralStack_1 = require("./ephemeralStack");
+const hostRuntime_1 = require("../hostRuntime");
 /** Detect the pipeline from standard CI env vars (GitHub Actions, GitLab CI). */
 function detectCiContext(env = process.env) {
     if (env.GITHUB_ACTIONS === 'true') {
@@ -68,10 +69,15 @@ async function ciProtectCommand(args, config) {
     }
     const runId = (args.runId || detected?.runId || '').trim() || undefined;
     const runUrl = (args.runUrl || detected?.runUrl || '').trim() || undefined;
+    // The runner's real substrate (VM / container / physical, hypervisor, cloud)
+    // from firmware + /proc facts: the fleet shows WHERE this pipeline ran, not
+    // just which provider claimed to run it.
+    const hostRuntime = (0, hostRuntime_1.getHostRuntime)();
     console.log('\x1b[1m\x1b[36mFullCourtDefense — CI runtime protection\x1b[0m');
     console.log(`  Pipeline: ${provider}/${repo}/${workflow}`);
     if (runId)
         console.log(`  Run:      ${runId}`);
+    console.log(`  Runner:   ${(0, hostRuntime_1.describeHostRuntime)(hostRuntime)}`);
     const sendLog = ciLogSender(apiUrl, apiKey, { provider, repo, workflow, runId, runUrl });
     const resp = await fetch(`${apiUrl}/api/cli/enroll/ci`, {
         method: 'POST',
@@ -83,6 +89,7 @@ async function ciProtectCommand(args, config) {
             runId,
             runUrl,
             cliVersion: (0, cliVersion_1.cliVersion)(),
+            hostRuntime,
         }),
     });
     const data = (await resp.json().catch(() => ({})));
@@ -106,6 +113,10 @@ async function ciProtectCommand(args, config) {
         FCD_MACHINE_ID: result.machineId,
         FCD_DEVELOPER_NAME: `ci@${repo.toLowerCase()}`,
         FCD_MACHINE_HOSTNAME: result.pipeline.key,
+        // No human at this keyboard: developer-scoped approvals route to the org
+        // queue (never self-approve), and policies written for CI runners fire here.
+        FCD_EPHEMERAL: '1',
+        FCD_MACHINE_KIND: 'ci',
     }, { githubEnvPath: process.env.GITHUB_ENV });
     console.log(`\x1b[32m✓ ${result.reused ? 'Pipeline re-enrolled' : 'Pipeline enrolled'}\x1b[0m  ${result.shieldName}`);
     console.log(`  Mode:    ${result.enforcementMode} · Config: ${savedPath}`);

package/dist/commands/hook.js

@@ -608,8 +608,7 @@ function tryLocalPolicyEnforcement(ctx, call, detail, opts = {}) {
     }
     const { operation, context } = (0, actionPolicyEngine_1.inferToolContext)(call.toolName, call.toolArgs);
     context.toolName = call.toolName;
-    context.developerName = developerId();
-    context.machineName = os.hostname();
+    (0, machineIdentity_1.stampMachineIdentityContext)(context, developerId());
     const declaredOperations = (0, actionPolicyEngine_1.deriveToolOperations)(call.toolName);
     const local = (0, actionPolicyEngine_1.evaluateActionPolicies)(policies, call.toolName, operation, context, declaredOperations);
     (0, hookIo_1.dbg)({ phase: 'policy_local_verdict', event: ctx.event, tool: call.toolName, operation, verdict: local.verdict, policyName: local.policyName, detail });
@@ -722,6 +721,9 @@ function machineMetadata(client = 'cursor') {
         ...(machineId ? { machineId } : {}),
         developerName: developerId(),
         machineName: os.hostname(),
+        // Same kind the local engine sees — the server's check-tool-call must
+        // evaluate kind-targeted policies identically to the offline path.
+        machineKind: (0, machineIdentity_1.localMachineKind)(),
         os: `${os.platform()} ${os.release()}`,
         username,
         cwd: process.cwd(),
@@ -760,10 +762,11 @@ function spoolLocalFinding(input) {
 /**
  * warn-action rule matches: the action PROCEEDS — spool each finding as a
  * 'warn' event so it lands in the org console/timeline without stopping work.
+ * Callers defer this until the verdict is known (see `deferLocalWarnings`), so
+ * a blocked action never also produces a "Warned" row.
  */
 function spoolLocalWarnings(warnings, toolName, operation) {
     for (const finding of warnings) {
-        (0, hookIo_1.dbg)({ phase: 'local_deterministic_warn', tool: toolName, ruleId: finding.ruleId, itemId: finding.itemId });
         spoolLocalFinding({ finding, toolName, operation, decision: 'warn' });
     }
 }
@@ -1092,9 +1095,25 @@ async function hookCommandInner(args, config, io) {
     //           permission prompt — Cursor `permission: "ask"`, Claude
     //           `permissionDecision: "ask"` — with our reason as the prompt text. No
     //           FCD dialog of its own; prompt events never ask.
+    // warn-action rule matches are held here until the verdict is known. A
+    // 'warn' record means "this proceeded, but note it" — so it is only written
+    // when the action actually proceeds. If the same action ends up BLOCKED
+    // (local guard, taint, or policy), the block record already tells the whole
+    // story and a sibling "Warned" row would read as if the action ran twice.
+    const pendingLocalWarnings = [];
+    const deferLocalWarnings = (warnings, toolName, operation) => {
+        for (const finding of warnings) {
+            (0, hookIo_1.dbg)({ phase: 'local_deterministic_warn', tool: toolName, ruleId: finding.ruleId, itemId: finding.itemId });
+            pendingLocalWarnings.push({ finding, toolName, operation });
+        }
+    };
     const respond = (blocked, userMsg, agentMsg) => {
         const ask = blocked === 'ask' && event !== 'prompt';
         const denied = blocked === true;
+        if (!denied && pendingLocalWarnings.length > 0) {
+            spoolLocalWarnings(pendingLocalWarnings.map(w => w.finding), pendingLocalWarnings[0].toolName, pendingLocalWarnings[0].operation);
+        }
+        pendingLocalWarnings.length = 0;
         let decision;
         if (hookFormat === 'claude') {
             if (event === 'prompt') {
@@ -1175,7 +1194,7 @@ async function hookCommandInner(args, config, io) {
     if (event === 'shell' || event === 'mcp' || event === 'file' || event === 'read') {
         await enforceActionPolicy({
             event, payload, apiUrl: apiUrl, shieldId: shieldId, shieldKey,
-            shadow, failClosed, timeoutMs, approvalMode, approvalTimeoutMs, approvalPollMs, respond,
+            shadow, failClosed, timeoutMs, approvalMode, approvalTimeoutMs, approvalPollMs, respond, deferLocalWarnings,
             effectivePolicyHash, localPolicies, client,
         });
         return;
@@ -1199,7 +1218,7 @@ async function hookCommandInner(args, config, io) {
             preferCached: shadow,
         });
         const promptOutcome = (0, deterministicGuard_1.resolveDeterministicOutcome)(opts => (0, deterministicGuard_1.scanDeterministicPrompt)(text, opts), (0, localSafetySnapshot_1.snapshotToScanOptions)(snapshot));
-        spoolLocalWarnings(promptOutcome.warnings, 'prompt', 'prompt');
+        deferLocalWarnings(promptOutcome.warnings, 'prompt', 'prompt');
         const localBlock = promptOutcome.blockingFinding;
         if (localBlock) {
             (0, hookIo_1.dbg)({ phase: 'local_deterministic_prompt_block', event, ruleId: localBlock.ruleId, category: localBlock.category });
@@ -1220,7 +1239,7 @@ async function hookCommandInner(args, config, io) {
         }
         await enforceShieldText({
             event, text, payload, apiUrl: apiUrl, shieldId: shieldId, shieldKey,
-            shadow, failClosed, timeoutMs, respond, client,
+            shadow, failClosed, timeoutMs, respond, deferLocalWarnings, client,
         });
         return;
     }
@@ -1304,7 +1323,7 @@ async function runTaintApproveOnce(ctx, event, call, sessId, taintFinding) {
     return false;
 }
 async function enforceActionPolicy(ctx) {
-    const { event, payload, apiUrl, shieldId, shieldKey, shadow, timeoutMs, respond, effectivePolicyHash } = ctx;
+    const { event, payload, apiUrl, shieldId, shieldKey, shadow, timeoutMs, respond, deferLocalWarnings, effectivePolicyHash } = ctx;
     const call = buildToolCall(event, payload);
     if (!call) {
         respond(false);
@@ -1324,7 +1343,7 @@ async function enforceActionPolicy(ctx) {
         cwd: typeof call.toolArgs.cwd === 'string' ? call.toolArgs.cwd : process.cwd(),
         inspectScripts: event === 'shell',
     }));
-    spoolLocalWarnings(toolOutcome.warnings, call.toolName, event);
+    deferLocalWarnings(toolOutcome.warnings, call.toolName, event);
     const localBlock = toolOutcome.blockingFinding;
     if (localBlock) {
         (0, hookIo_1.dbg)({ phase: 'local_deterministic_block', event, tool: call.toolName, ruleId: localBlock.ruleId, category: localBlock.category });
@@ -1427,8 +1446,7 @@ async function enforceActionPolicy(ctx) {
     if (ctx.localPolicies && ctx.localPolicies.length > 0) {
         const { operation: localOp, context: localCtx } = (0, actionPolicyEngine_1.inferToolContext)(call.toolName, call.toolArgs);
         localCtx.toolName = call.toolName;
-        localCtx.developerName = developerId();
-        localCtx.machineName = os.hostname();
+        (0, machineIdentity_1.stampMachineIdentityContext)(localCtx, developerId());
         const localVerdict = (0, actionPolicyEngine_1.evaluateActionPolicies)(ctx.localPolicies, call.toolName, localOp, localCtx, (0, actionPolicyEngine_1.deriveToolOperations)(call.toolName));
         (0, hookIo_1.dbg)({ phase: 'policy_local_first', event, tool: call.toolName, operation: localOp, verdict: localVerdict.verdict, policyName: localVerdict.policyName });
         if (localVerdict.verdict === 'allow') {

package/dist/commands/mcpGateway.js

@@ -254,6 +254,7 @@ function machineMetadata(developerName, agentClient = 'cursor') {
         ...(machineId ? { machineId } : {}),
         developerName: developerName || machineScopedUser(),
         machineName: os.hostname(),
+        machineKind: (0, machineIdentity_1.localMachineKind)(),
         os: `${os.platform()} ${os.release()}`,
         username: safeUserName(),
         ipAddress: firstPrivateIp(),
@@ -1159,9 +1160,7 @@ class McpGatewayServer {
                 if (cachedPolicies && cachedPolicies.length > 0) {
                     const context = inferred.context;
                     context.toolName = toolName;
-                    if (this.gatewayConfig.developerName)
-                        context.developerName = this.gatewayConfig.developerName;
-                    context.machineName = os.hostname();
+                    (0, machineIdentity_1.stampMachineIdentityContext)(context, this.gatewayConfig.developerName);
                     const local = (0, actionPolicyEngine_1.evaluateActionPolicies)(cachedPolicies, toolName, localOperation, context, (0, actionPolicyEngine_1.deriveToolOperations)(toolName));
                     if (local.verdict === 'block' || local.verdict === 'require_approval') {
                         const wouldWhat = local.verdict === 'require_approval' ? 'require approval for' : 'block';
@@ -1205,9 +1204,7 @@ class McpGatewayServer {
                 const localOperation = operation || inferred.operation;
                 const context = inferred.context;
                 context.toolName = toolName;
-                if (this.gatewayConfig.developerName)
-                    context.developerName = this.gatewayConfig.developerName;
-                context.machineName = os.hostname();
+                (0, machineIdentity_1.stampMachineIdentityContext)(context, this.gatewayConfig.developerName);
                 const local = (0, actionPolicyEngine_1.evaluateActionPolicies)(cachedPolicies, toolName, localOperation, context, (0, actionPolicyEngine_1.deriveToolOperations)(toolName));
                 if (local.verdict === 'block') {
                     const reason = local.reason || `${toolName}: blocked by org Action Policy`;
@@ -1275,9 +1272,7 @@ class McpGatewayServer {
                         const localOperation = operation || inferred.operation;
                         const context = inferred.context;
                         context.toolName = toolName;
-                        if (this.gatewayConfig.developerName)
-                            context.developerName = this.gatewayConfig.developerName;
-                        context.machineName = os.hostname();
+                        (0, machineIdentity_1.stampMachineIdentityContext)(context, this.gatewayConfig.developerName);
                         const local = (0, actionPolicyEngine_1.evaluateActionPolicies)(cachedPolicies, toolName, localOperation, context, (0, actionPolicyEngine_1.deriveToolOperations)(toolName));
                         const blocking = local.verdict === 'block' || local.verdict === 'require_approval';
                         if (blocking && !reportOnlyMode) {

package/dist/commands/workloadProtect.d.ts

@@ -1,4 +1,16 @@
 import { BotGuardConfig } from '../config';
+import { type HostRuntime } from '../hostRuntime';
+/**
+ * A workload claim must match the machine's own fingerprint. `workload-protect`
+ * run on a developer's laptop (or a long-lived VM) with `--kind container`
+ * would file that machine under Containers with a 24h TTL and no human — the
+ * exact attribution mistake this guard exists to stop. Only a HIGH-confidence
+ * physical verdict refuses; unknown / low-confidence hosts proceed (exotic
+ * sandboxes with no readable firmware must still be protectable).
+ */
+export declare function assertWorkloadSubstrate(kind: string, rt: HostRuntime, options?: {
+    force?: boolean;
+}): void;
 /**
  * `fullcourtdefense workload-protect` — one-command runtime protection for
  * EPHEMERAL WORKLOADS: containers, Kubernetes jobs, serverless functions and

package/dist/commands/workloadProtect.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertWorkloadSubstrate = assertWorkloadSubstrate;
 exports.detectWorkloadContext = detectWorkloadContext;
 exports.workloadProtectCommand = workloadProtectCommand;
 const fs = __importStar(require("fs"));
@@ -41,6 +42,27 @@ const path = __importStar(require("path"));
 const config_1 = require("../config");
 const cliVersion_1 = require("../cliVersion");
 const ephemeralStack_1 = require("./ephemeralStack");
+const hostRuntime_1 = require("../hostRuntime");
+/**
+ * A workload claim must match the machine's own fingerprint. `workload-protect`
+ * run on a developer's laptop (or a long-lived VM) with `--kind container`
+ * would file that machine under Containers with a 24h TTL and no human — the
+ * exact attribution mistake this guard exists to stop. Only a HIGH-confidence
+ * physical verdict refuses; unknown / low-confidence hosts proceed (exotic
+ * sandboxes with no readable firmware must still be protectable).
+ */
+function assertWorkloadSubstrate(kind, rt, options = {}) {
+    const claimsIsolated = kind === 'container' || kind === 'kubernetes' || kind === 'serverless';
+    if (!claimsIsolated || rt.substrate !== 'physical' || rt.confidence !== 'high')
+        return;
+    if (options.force) {
+        console.warn(`  \x1b[33mWarning:\x1b[0m enrolling as ${kind}, but this host looks like a physical machine (${rt.evidence.join('; ')}). Continuing because --force true.`);
+        return;
+    }
+    throw new Error(`This host looks like a PHYSICAL machine, not a ${kind} (${rt.evidence.join('; ')}). `
+        + 'workload-protect is for containers, pods and functions. On a laptop or long-lived VM run `fullcourtdefense onboard` instead, '
+        + 'or pass --force true if this really is a disposable workload host.');
+}
 /** Cloud coding agents that run as unattended workloads (env markers they set). */
 const CLOUD_AGENT_MARKERS = [
     ['CURSOR_AGENT', 'cursor-cloud-agent'],
@@ -109,10 +131,16 @@ async function workloadProtectCommand(args, config) {
     if (args.ttlHours !== undefined && (!Number.isFinite(ttlHours) || ttlHours <= 0)) {
         throw new Error('--ttl-hours must be a positive number of hours (1–168).');
     }
+    // What this machine REALLY is, from firmware / cgroup / marker facts — sent
+    // with the enrollment so the fleet attributes every event to a verified
+    // substrate, not to the `--kind` the caller claimed.
+    const hostRuntime = (0, hostRuntime_1.getHostRuntime)();
+    assertWorkloadSubstrate(kind, hostRuntime, { force: args.force === 'true' });
     console.log('\x1b[1m\x1b[36mFullCourtDefense — workload runtime protection\x1b[0m');
     console.log(`  Workload: ${kind}/${name}${environment ? `/${environment}` : ''}`);
     if (instanceId)
         console.log(`  Instance: ${instanceId}`);
+    console.log(`  Detected: ${(0, hostRuntime_1.describeHostRuntime)(hostRuntime)}`);
     const resp = await fetch(`${apiUrl}/api/cli/enroll/workload`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey },
@@ -126,6 +154,7 @@ async function workloadProtectCommand(args, config) {
             // Read from our own package.json — npm_package_version only exists under
             // `npm run`, never when the binary runs from a container entrypoint.
             cliVersion: (0, cliVersion_1.cliVersion)(),
+            hostRuntime,
         }),
     });
     const data = (await resp.json().catch(() => ({})));
@@ -147,6 +176,8 @@ async function workloadProtectCommand(args, config) {
         FCD_DEVELOPER_NAME: `workload@${result.workload.name.toLowerCase()}`,
         FCD_MACHINE_HOSTNAME: result.workload.key,
         FCD_EPHEMERAL: '1',
+        // Policy engine context: policies written for containers fire here, laptop-only ones never do.
+        FCD_MACHINE_KIND: 'workload',
     };
     const envFilePath = args.identityFile === 'false'
         ? undefined

package/dist/hostRuntime.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Host runtime fingerprint — WHAT KIND OF MACHINE is this process really on:
+ * a container, a virtual machine, or physical hardware; and, when it can be
+ * told from local facts, which container runtime / hypervisor / cloud.
+ *
+ * Why this exists: `ci-protect` and `workload-protect` let the caller CLAIM a
+ * kind (`--kind container`). Fleet attribution must not rest on a claim. Every
+ * enrollment and heartbeat carries this fingerprint so the console can state
+ * the source of every event precisely ("Docker container on a Google Cloud
+ * VM", "Azure VM — GitHub-hosted runner", "physical Windows laptop") and flag a
+ * mismatch between what was claimed and what the machine itself reports.
+ *
+ * Evidence only, no network: DMI/SMBIOS (`/sys/class/dmi/id`), `/proc`,
+ * well-known marker files, platform env vars, and on Windows/macOS one local
+ * system query. Never a metadata endpoint — this runs at enrollment inside
+ * customer infrastructure and must stay offline-safe and side-effect free.
+ *
+ * Pure core (`detectHostRuntime(probe)`) with an injectable probe so every
+ * substrate has a unit test; `getHostRuntime()` wires the real OS and caches.
+ */
+export type HostSubstrate = 'container' | 'vm' | 'physical' | 'unknown';
+export interface HostRuntime {
+    /** Schema tag so the backend can evolve parsing. */
+    v: 1;
+    substrate: HostSubstrate;
+    /** How sure the substrate verdict is: `high` = a definitive marker, `medium` = strong inference, `low` = weak/absent signals. */
+    confidence: 'high' | 'medium' | 'low';
+    /** Container engine / sandbox when substrate is `container`. */
+    containerRuntime?: 'docker' | 'podman' | 'containerd' | 'cri-o' | 'lxc' | 'gvisor' | 'windows-container' | 'unknown';
+    /** Platform that scheduled the container / function, when known. */
+    orchestrator?: 'kubernetes' | 'ecs' | 'cloud-run' | 'lambda' | 'azure-functions' | 'azure-container-apps' | 'nomad' | 'fly';
+    /** Hypervisor when substrate is `vm` (or the VM under a container, when readable). */
+    hypervisor?: 'kvm' | 'hyper-v' | 'vmware' | 'xen' | 'virtualbox' | 'parallels' | 'qemu' | 'firecracker' | 'apple-vz' | 'nitro' | 'unknown';
+    /** Cloud / hosting provider inferred from firmware or platform markers. */
+    cloud?: 'gcp' | 'aws' | 'azure' | 'oracle' | 'digitalocean' | 'hetzner' | 'alibaba' | 'openstack' | 'fly' | 'unknown';
+    /** CI system running this process, when any. */
+    ci?: {
+        provider: 'github-actions' | 'gitlab-ci' | 'jenkins' | 'circleci' | 'azure-pipelines' | 'bitbucket' | 'buildkite' | 'other';
+        hosted: 'provider-hosted' | 'self-hosted' | 'unknown';
+    };
+    os: 'linux' | 'windows' | 'macos' | 'other';
+    arch: string;
+    /** Short, deterministic facts that produced the verdict — shown to admins verbatim. Max ~12. */
+    evidence: string[];
+    detectedAt: string;
+}
+/** Everything the detector reads. Injected in tests; real OS in production. */
+export interface HostRuntimeProbe {
+    platform: NodeJS.Platform;
+    arch: string;
+    env: NodeJS.ProcessEnv;
+    exists: (p: string) => boolean;
+    read: (p: string) => string | undefined;
+    /** Windows: `Manufacturer|Model|SystemFamily` from Win32_ComputerSystem; macOS: `hw.model|kern.hv_vmm_present`. */
+    systemInfo: () => string | undefined;
+}
+/** Pure detector. Every read goes through `probe` so each substrate has a fixture test. */
+export declare function detectHostRuntime(probe: HostRuntimeProbe, now?: Date): HostRuntime;
+export declare function realHostRuntimeProbe(): HostRuntimeProbe;
+/**
+ * Fingerprint of the machine this process runs on (cached per process). Not
+ * for the hook hot path: Windows/macOS spend one local system query (reg.exe /
+ * sysctl — tens of milliseconds, never PowerShell).
+ * Callers: enrollment commands and the daemon heartbeat.
+ */
+export declare function getHostRuntime(): HostRuntime;
+/** One line for terminals: "container (docker) · kubernetes · linux x64". */
+export declare function describeHostRuntime(rt: HostRuntime): string;

package/dist/hostRuntime.js

@@ -0,0 +1,509 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectHostRuntime = detectHostRuntime;
+exports.realHostRuntimeProbe = realHostRuntimeProbe;
+exports.getHostRuntime = getHostRuntime;
+exports.describeHostRuntime = describeHostRuntime;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const MAX_EVIDENCE = 12;
+function push(evidence, fact) {
+    if (evidence.length < MAX_EVIDENCE && !evidence.includes(fact))
+        evidence.push(fact);
+}
+function lower(value) {
+    return (value || '').trim().toLowerCase();
+}
+/** Firmware vendor strings → hypervisor + cloud. Order matters: most specific first. */
+function classifyFirmware(text) {
+    const t = text.toLowerCase();
+    if (t.includes('google'))
+        return { hypervisor: 'kvm', cloud: 'gcp', label: 'Google Compute Engine' };
+    if (t.includes('amazon ec2') || t.includes('amazon'))
+        return { hypervisor: 'nitro', cloud: 'aws', label: 'Amazon EC2' };
+    if (t.includes('hvm domu'))
+        return { hypervisor: 'xen', cloud: 'aws', label: 'Amazon EC2 (Xen)' };
+    if (t.includes('7783-7084-3265-9085-8269-3286-77'))
+        return { hypervisor: 'hyper-v', cloud: 'azure', label: 'Microsoft Azure' };
+    if (t.includes('microsoft corporation') && t.includes('virtual machine'))
+        return { hypervisor: 'hyper-v', label: 'Hyper-V' };
+    if (t.includes('vmware'))
+        return { hypervisor: 'vmware', label: 'VMware' };
+    if (t.includes('virtualbox') || t.includes('innotek'))
+        return { hypervisor: 'virtualbox', label: 'VirtualBox' };
+    if (t.includes('parallels'))
+        return { hypervisor: 'parallels', label: 'Parallels' };
+    if (t.includes('digitalocean'))
+        return { hypervisor: 'kvm', cloud: 'digitalocean', label: 'DigitalOcean' };
+    if (t.includes('hetzner'))
+        return { hypervisor: 'kvm', cloud: 'hetzner', label: 'Hetzner' };
+    if (t.includes('alibaba'))
+        return { hypervisor: 'kvm', cloud: 'alibaba', label: 'Alibaba Cloud' };
+    if (t.includes('oraclecloud') || t.includes('oracle cloud'))
+        return { hypervisor: 'kvm', cloud: 'oracle', label: 'Oracle Cloud' };
+    if (t.includes('openstack'))
+        return { hypervisor: 'kvm', cloud: 'openstack', label: 'OpenStack' };
+    if (t.includes('firecracker'))
+        return { hypervisor: 'firecracker', label: 'Firecracker' };
+    if (t.includes('qemu') || t.includes('standard pc'))
+        return { hypervisor: 'qemu', label: 'QEMU/KVM' };
+    if (t.includes('kvm'))
+        return { hypervisor: 'kvm', label: 'KVM' };
+    if (t.includes('xen'))
+        return { hypervisor: 'xen', label: 'Xen' };
+    if (t.includes('bochs'))
+        return { hypervisor: 'qemu', label: 'Bochs/QEMU' };
+    return {};
+}
+function detectCi(env, evidence) {
+    if (env.GITHUB_ACTIONS === 'true') {
+        const hosted = lower(env.RUNNER_ENVIRONMENT);
+        push(evidence, `env:GITHUB_ACTIONS runner=${hosted || 'unknown'}`);
+        return { provider: 'github-actions', hosted: hosted === 'github-hosted' ? 'provider-hosted' : hosted === 'self-hosted' ? 'self-hosted' : 'unknown' };
+    }
+    if (env.GITLAB_CI === 'true') {
+        const shared = /gitlab\.com/i.test(env.CI_SERVER_HOST || '') && /shared|saas|gitlab-runner/i.test(env.CI_RUNNER_DESCRIPTION || 'shared');
+        push(evidence, `env:GITLAB_CI server=${env.CI_SERVER_HOST || 'unknown'}`);
+        return { provider: 'gitlab-ci', hosted: shared ? 'provider-hosted' : env.CI_RUNNER_DESCRIPTION ? 'self-hosted' : 'unknown' };
+    }
+    if (env.JENKINS_URL) {
+        push(evidence, 'env:JENKINS_URL');
+        return { provider: 'jenkins', hosted: 'self-hosted' };
+    }
+    if (env.CIRCLECI === 'true') {
+        push(evidence, 'env:CIRCLECI');
+        return { provider: 'circleci', hosted: 'provider-hosted' };
+    }
+    if (env.TF_BUILD === 'True' || env.TF_BUILD === 'true') {
+        push(evidence, 'env:TF_BUILD');
+        return { provider: 'azure-pipelines', hosted: env.AGENT_NAME?.startsWith('Hosted') || env.AGENT_NAME?.startsWith('Azure Pipelines') ? 'provider-hosted' : 'unknown' };
+    }
+    if (env.BITBUCKET_BUILD_NUMBER) {
+        push(evidence, 'env:BITBUCKET_BUILD_NUMBER');
+        return { provider: 'bitbucket', hosted: 'provider-hosted' };
+    }
+    if (env.BUILDKITE === 'true') {
+        push(evidence, 'env:BUILDKITE');
+        return { provider: 'buildkite', hosted: 'self-hosted' };
+    }
+    if (env.CI === 'true' || env.CI === '1') {
+        push(evidence, 'env:CI');
+        return { provider: 'other', hosted: 'unknown' };
+    }
+    return undefined;
+}
+function detectLinux(probe, out) {
+    const { env, exists, read } = probe;
+    const evidence = out.evidence;
+    // ── Serverless / managed platforms (env markers set by the platform, not the user) ──
+    if (env.AWS_LAMBDA_FUNCTION_NAME) {
+        // Lambda executes in a Firecracker microVM; the function code sees a container-like rootfs.
+        push(evidence, 'env:AWS_LAMBDA_FUNCTION_NAME');
+        out.substrate = 'vm';
+        out.confidence = 'high';
+        out.hypervisor = 'firecracker';
+        out.cloud = 'aws';
+        out.orchestrator = 'lambda';
+        return;
+    }
+    if (env.K_SERVICE && env.K_REVISION) {
+        push(evidence, 'env:K_SERVICE/K_REVISION (Knative)');
+        out.orchestrator = 'cloud-run';
+        if (env.CLOUD_RUN_JOB || env.K_CONFIGURATION || !env.KUBERNETES_SERVICE_HOST) {
+            out.substrate = 'container';
+            out.confidence = 'high';
+            out.containerRuntime = 'gvisor';
+            out.cloud = 'gcp';
+            push(evidence, 'cloud-run sandbox (no KUBERNETES_SERVICE_HOST)');
+            return;
+        }
+    }
+    if (env.FUNCTIONS_WORKER_RUNTIME && env.WEBSITE_SITE_NAME) {
+        push(evidence, 'env:FUNCTIONS_WORKER_RUNTIME');
+        out.substrate = 'container';
+        out.confidence = 'high';
+        out.orchestrator = 'azure-functions';
+        out.cloud = 'azure';
+        out.containerRuntime = 'unknown';
+        return;
+    }
+    if (env.ECS_CONTAINER_METADATA_URI_V4 || env.ECS_CONTAINER_METADATA_URI) {
+        push(evidence, 'env:ECS_CONTAINER_METADATA_URI');
+        out.substrate = 'container';
+        out.confidence = 'high';
+        out.orchestrator = 'ecs';
+        out.cloud = 'aws';
+        out.containerRuntime = 'docker';
+        return;
+    }
+    if (env.FLY_APP_NAME && env.FLY_MACHINE_ID) {
+        push(evidence, 'env:FLY_MACHINE_ID');
+        out.substrate = 'vm';
+        out.confidence = 'high';
+        out.hypervisor = 'firecracker';
+        out.cloud = 'fly';
+        out.orchestrator = 'fly';
+        return;
+    }
+    if (env.CONTAINER_APP_NAME && env.CONTAINER_APP_REVISION) {
+        push(evidence, 'env:CONTAINER_APP_REVISION');
+        out.orchestrator = 'azure-container-apps';
+        out.cloud = 'azure';
+    }
+    if (env.NOMAD_ALLOC_ID) {
+        push(evidence, 'env:NOMAD_ALLOC_ID');
+        out.orchestrator = 'nomad';
+    }
+    // ── Container markers (definitive) ──
+    let container;
+    if (exists('/.dockerenv')) {
+        container = 'docker';
+        push(evidence, '/.dockerenv present');
+    }
+    if (exists('/run/.containerenv')) {
+        container = container || 'podman';
+        push(evidence, '/run/.containerenv present (podman)');
+    }
+    const cgroup1 = read('/proc/1/cgroup') || '';
+    const selfCgroup = read('/proc/self/cgroup') || '';
+    const cgroupText = `${cgroup1}\n${selfCgroup}`;
+    if (/kubepods/.test(cgroupText)) {
+        container = container || 'containerd';
+        push(evidence, 'cgroup: kubepods');
+        out.orchestrator = out.orchestrator || 'kubernetes';
+    }
+    if (/\/docker[/-]/.test(cgroupText)) {
+        container = container || 'docker';
+        push(evidence, 'cgroup: docker');
+    }
+    if (/cri-containerd|containerd/.test(cgroupText)) {
+        container = container || 'containerd';
+        push(evidence, 'cgroup: containerd');
+    }
+    if (/crio-|cri-o/.test(cgroupText)) {
+        container = container || 'cri-o';
+        push(evidence, 'cgroup: cri-o');
+    }
+    if (/libpod|podman/.test(cgroupText)) {
+        container = container || 'podman';
+        push(evidence, 'cgroup: libpod');
+    }
+    if (/\/lxc\//.test(cgroupText)) {
+        container = container || 'lxc';
+        push(evidence, 'cgroup: lxc');
+    }
+    if (env.KUBERNETES_SERVICE_HOST || exists('/var/run/secrets/kubernetes.io/serviceaccount/token')) {
+        out.orchestrator = out.orchestrator || 'kubernetes';
+        container = container || 'containerd';
+        push(evidence, env.KUBERNETES_SERVICE_HOST ? 'env:KUBERNETES_SERVICE_HOST' : 'k8s serviceaccount mounted');
+    }
+    if (lower(env.container)) {
+        push(evidence, `env:container=${lower(env.container)}`);
+        if (!container)
+            container = lower(env.container) === 'podman' ? 'podman' : lower(env.container) === 'lxc' ? 'lxc' : 'unknown';
+    }
+    // cgroup v2 with a private cgroup namespace: PID 1 reports the root cgroup.
+    // On a host with systemd PID 1 lives in /init.scope, so a bare "0::/" is a
+    // strong container signal. Only counted alongside a non-init PID 1.
+    const pid1Comm = lower(read('/proc/1/comm'));
+    const pid1Sched = lower((read('/proc/1/sched') || '').split('\n')[0]);
+    const pid1IsInit = pid1Comm === 'systemd' || pid1Comm === 'init' || pid1Sched.startsWith('systemd') || pid1Sched.startsWith('init');
+    if (!container && /^0::\/\s*$/m.test(cgroup1) && pid1Comm && !pid1IsInit) {
+        container = 'unknown';
+        push(evidence, `cgroup v2 root + pid1=${pid1Comm}`);
+    }
+    const mountinfo = read('/proc/self/mountinfo') || '';
+    if (!container && /\/docker\/containers\//.test(mountinfo)) {
+        container = 'docker';
+        push(evidence, 'mountinfo: docker containers');
+    }
+    if (/ \/ [^ ]+ [^ ]+ overlay /.test(mountinfo) || /^\S+ \S+ \S+ \S+ \/ .* - overlay /m.test(mountinfo)) {
+        push(evidence, 'rootfs: overlay');
+        if (!container && pid1Comm && !pid1IsInit)
+            container = 'unknown';
+    }
+    if (out.orchestrator === 'cloud-run' && !container) {
+        container = 'gvisor';
+        out.cloud = 'gcp';
+    }
+    // ── Virtualization markers (firmware) — readable inside most containers too ──
+    const dmi = ['sys_vendor', 'product_name', 'board_vendor', 'bios_vendor', 'chassis_asset_tag', 'product_version']
+        .map(name => read(`/sys/class/dmi/id/${name}`))
+        .filter(Boolean)
+        .join(' | ');
+    const deviceTree = read('/proc/device-tree/hypervisor/compatible') || read('/sys/firmware/devicetree/base/hypervisor/compatible');
+    const cpuinfo = read('/proc/cpuinfo') || '';
+    const hypervisorFlag = /^flags\s*:.*\bhypervisor\b/m.test(cpuinfo);
+    const xenType = lower(read('/sys/hypervisor/type'));
+    const firmware = classifyFirmware(`${dmi} ${deviceTree || ''} ${xenType}`);
+    if (firmware.hypervisor) {
+        out.hypervisor = firmware.hypervisor;
+        if (firmware.cloud)
+            out.cloud = out.cloud || firmware.cloud;
+        push(evidence, `dmi: ${firmware.label}`);
+    }
+    else if (hypervisorFlag) {
+        out.hypervisor = 'unknown';
+        push(evidence, 'cpuinfo: hypervisor flag');
+    }
+    else if (dmi) {
+        push(evidence, `dmi: ${dmi.split(' | ')[0].slice(0, 40)}`);
+    }
+    // ── Verdict ──
+    if (container) {
+        out.substrate = 'container';
+        out.containerRuntime = container;
+        out.confidence = container === 'unknown' ? 'medium' : 'high';
+        return;
+    }
+    if (out.hypervisor) {
+        out.substrate = 'vm';
+        out.confidence = firmware.hypervisor ? 'high' : 'medium';
+        return;
+    }
+    if (dmi || pid1IsInit) {
+        // Real firmware vendor with no hypervisor markers, and a normal init: bare metal.
+        out.substrate = 'physical';
+        out.confidence = dmi ? 'high' : 'medium';
+        if (pid1IsInit)
+            push(evidence, `pid1=${pid1Comm || 'init'}`);
+        return;
+    }
+    out.substrate = 'unknown';
+    out.confidence = 'low';
+    push(evidence, 'no firmware, cgroup or marker evidence readable');
+}
+function detectWindows(probe, out) {
+    const { env, exists } = probe;
+    const evidence = out.evidence;
+    // Windows containers: the sandbox mount point and the mapped-directories
+    // folder exist only inside a Windows Server / Hyper-V isolated container.
+    if (env.CONTAINER_SANDBOX_MOUNT_POINT || exists('C:\\ContainerMappedDirectories')) {
+        push(evidence, env.CONTAINER_SANDBOX_MOUNT_POINT ? 'env:CONTAINER_SANDBOX_MOUNT_POINT' : 'C:\\ContainerMappedDirectories present');
+        out.substrate = 'container';
+        out.confidence = 'high';
+        out.containerRuntime = 'windows-container';
+        return;
+    }
+    const info = probe.systemInfo() || '';
+    const firmware = classifyFirmware(info);
+    if (info)
+        push(evidence, `smbios: ${info.slice(0, 60)}`);
+    if (firmware.hypervisor) {
+        out.substrate = 'vm';
+        out.confidence = 'high';
+        out.hypervisor = firmware.hypervisor;
+        if (firmware.cloud)
+            out.cloud = firmware.cloud;
+        push(evidence, `firmware: ${firmware.label}`);
+        return;
+    }
+    if (info) {
+        out.substrate = 'physical';
+        out.confidence = 'high';
+        return;
+    }
+    out.substrate = 'unknown';
+    out.confidence = 'low';
+    push(evidence, 'system info unavailable');
+}
+function detectMac(probe, out) {
+    const info = probe.systemInfo() || '';
+    const evidence = out.evidence;
+    const [model = '', hvPresent = ''] = info.split('|');
+    if (model)
+        push(evidence, `hw.model=${model.trim().slice(0, 40)}`);
+    const firmware = classifyFirmware(model);
+    if (firmware.hypervisor) {
+        out.substrate = 'vm';
+        out.confidence = 'high';
+        out.hypervisor = firmware.hypervisor;
+        push(evidence, `firmware: ${firmware.label}`);
+        return;
+    }
+    if (hvPresent.trim() === '1') {
+        push(evidence, 'kern.hv_vmm_present=1');
+        out.substrate = 'vm';
+        out.confidence = 'high';
+        out.hypervisor = 'apple-vz';
+        return;
+    }
+    if (info) {
+        out.substrate = 'physical';
+        out.confidence = 'high';
+        return;
+    }
+    out.substrate = 'unknown';
+    out.confidence = 'low';
+    push(evidence, 'sysctl unavailable');
+}
+/** Pure detector. Every read goes through `probe` so each substrate has a fixture test. */
+function detectHostRuntime(probe, now = new Date()) {
+    const out = {
+        v: 1,
+        substrate: 'unknown',
+        confidence: 'low',
+        os: probe.platform === 'linux' ? 'linux' : probe.platform === 'win32' ? 'windows' : probe.platform === 'darwin' ? 'macos' : 'other',
+        arch: probe.arch,
+        evidence: [],
+        detectedAt: now.toISOString(),
+    };
+    const ci = detectCi(probe.env, out.evidence);
+    if (ci)
+        out.ci = ci;
+    if (probe.platform === 'linux')
+        detectLinux(probe, out);
+    else if (probe.platform === 'win32')
+        detectWindows(probe, out);
+    else if (probe.platform === 'darwin')
+        detectMac(probe, out);
+    else {
+        out.evidence.push(`platform ${probe.platform} not fingerprinted`);
+    }
+    // Provider-hosted CI runners are the provider's cloud VMs; name the cloud
+    // when the firmware did not (GitHub-hosted runners are Azure VMs).
+    if (ci?.provider === 'github-actions' && ci.hosted === 'provider-hosted' && out.substrate === 'vm' && !out.cloud)
+        out.cloud = 'azure';
+    if (ci?.provider === 'gitlab-ci' && ci.hosted === 'provider-hosted' && !out.cloud)
+        out.cloud = 'gcp';
+    return out;
+}
+function safeRead(p) {
+    try {
+        const text = fs.readFileSync(p, 'utf8');
+        return text.length > 64 * 1024 ? text.slice(0, 64 * 1024) : text;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Windows firmware identity WITHOUT PowerShell. SMBIOS values are mirrored
+ * into `HKLM\HARDWARE\DESCRIPTION\System\BIOS` at boot (SystemManufacturer /
+ * SystemProductName / SystemFamily = Win32_ComputerSystem Manufacturer /
+ * Model / SystemFamily). One `reg.exe query` (~30ms) instead of a PowerShell
+ * + CIM startup (seconds, and PowerShell is exactly what EDR-hardened fleets
+ * block — the daemon heartbeat must never wait on it).
+ */
+function windowsFirmwareInfo() {
+    const out = (0, child_process_1.execFileSync)('reg', ['query', 'HKLM\\HARDWARE\\DESCRIPTION\\System\\BIOS'], { encoding: 'utf8', windowsHide: true, timeout: 4000 });
+    const value = (name) => {
+        const match = out.match(new RegExp(`^\\s*${name}\\s+REG_SZ\\s+(.*)$`, 'im'));
+        return match ? match[1].trim() : '';
+    };
+    const parts = [value('SystemManufacturer'), value('SystemProductName'), value('SystemFamily')];
+    return parts.some(Boolean) ? parts.join('|') : undefined;
+}
+function realSystemInfo(platform) {
+    try {
+        if (platform === 'win32')
+            return windowsFirmwareInfo();
+        if (platform === 'darwin') {
+            const model = (0, child_process_1.execFileSync)('sysctl', ['-n', 'hw.model'], { encoding: 'utf8', timeout: 3000 }).trim();
+            let hv = '';
+            try {
+                hv = (0, child_process_1.execFileSync)('sysctl', ['-n', 'kern.hv_vmm_present'], { encoding: 'utf8', timeout: 3000 }).trim();
+            }
+            catch { /* older macOS */ }
+            return `${model}|${hv}`;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function realHostRuntimeProbe() {
+    const platform = os.platform();
+    return {
+        platform,
+        arch: os.arch(),
+        env: process.env,
+        exists: p => { try {
+            return fs.existsSync(p);
+        }
+        catch {
+            return false;
+        } },
+        read: safeRead,
+        systemInfo: () => realSystemInfo(platform),
+    };
+}
+let cached;
+/**
+ * Fingerprint of the machine this process runs on (cached per process). Not
+ * for the hook hot path: Windows/macOS spend one local system query (reg.exe /
+ * sysctl — tens of milliseconds, never PowerShell).
+ * Callers: enrollment commands and the daemon heartbeat.
+ */
+function getHostRuntime() {
+    if (cached)
+        return cached;
+    // Test seam for the offline drills (they simulate a pod / CI runner on a
+    // developer laptop): a complete fingerprint as JSON. Ignored unless valid.
+    const fixture = process.env.FCD_TEST_HOST_RUNTIME_JSON;
+    if (fixture) {
+        try {
+            const parsed = JSON.parse(fixture);
+            if (parsed && parsed.v === 1 && typeof parsed.substrate === 'string')
+                return (cached = parsed);
+        }
+        catch { /* fall through to real detection */ }
+    }
+    cached = detectHostRuntime(realHostRuntimeProbe());
+    return cached;
+}
+/** One line for terminals: "container (docker) · kubernetes · linux x64". */
+function describeHostRuntime(rt) {
+    const parts = [];
+    if (rt.substrate === 'container')
+        parts.push(`container${rt.containerRuntime && rt.containerRuntime !== 'unknown' ? ` (${rt.containerRuntime})` : ''}`);
+    else if (rt.substrate === 'vm')
+        parts.push(`virtual machine${rt.hypervisor && rt.hypervisor !== 'unknown' ? ` (${rt.hypervisor})` : ''}`);
+    else if (rt.substrate === 'physical')
+        parts.push('physical machine');
+    else
+        parts.push('unknown substrate');
+    if (rt.orchestrator)
+        parts.push(rt.orchestrator);
+    if (rt.cloud && rt.cloud !== 'unknown')
+        parts.push(rt.cloud);
+    if (rt.ci)
+        parts.push(`${rt.ci.provider}${rt.ci.hosted === 'provider-hosted' ? ' hosted runner' : rt.ci.hosted === 'self-hosted' ? ' self-hosted runner' : ''}`);
+    parts.push(`${rt.os} ${rt.arch}`);
+    return parts.join(' · ');
+}

package/dist/machineIdentity.d.ts

@@ -19,5 +19,31 @@ export declare function normalizeHostname(raw: string): string;
  * (SHA-256, 32 hex chars) so we never transmit the raw hardware UUID.
  */
 export declare function getMachineIdentity(): MachineIdentity;
+export type LocalMachineKind = 'workstation' | 'ci' | 'workload';
+/**
+ * Which KIND of fleet machine this process belongs to — the value the policy
+ * engine reads as `context.machineKind`, so a policy written for containers
+ * fires in containers and never on a laptop (and vice versa).
+ *
+ * Order: `FCD_MACHINE_KIND` (exported by ci-protect / workload-protect into
+ * the job/container env), then the ephemeral identity marker those commands
+ * write next to the credentials, then the FCD_DEVELOPER_NAME prefix older
+ * ephemeral stacks exported (`ci@…` / `workload@…`). Anything else is a
+ * workstation. Cheap: one env read, at most one small file read per process.
+ */
+export declare function localMachineKind(env?: NodeJS.ProcessEnv): LocalMachineKind;
+/** Test seam: forget the cached kind (the marker / env changed). */
+export declare function resetLocalMachineKindCache(): void;
+/**
+ * Stamp THIS machine's identity onto a policy-engine context — the single
+ * place the hook and the MCP gateway describe "who/where" to the engine, so
+ * `appliesTo.machineNames` / `appliesTo.machineKinds` / `developerName`
+ * targeting sees identical values on every enforcement point.
+ *
+ * `machineName` is the raw OS hostname (what admins pin in appliesTo);
+ * `machineKind` is what `localMachineKind()` resolved (workstation / ci /
+ * workload). `developerName` is only set when the caller resolved one.
+ */
+export declare function stampMachineIdentityContext<T extends Record<string, string>>(context: T, developerName?: string): T;
 /** Suggested per-machine Shield name, e.g. `boazl@boaz-pc · Windows 11`. */
 export declare function suggestedShieldName(identity?: MachineIdentity): string;

package/dist/machineIdentity.js

@@ -35,6 +35,9 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeHostname = normalizeHostname;
 exports.getMachineIdentity = getMachineIdentity;
+exports.localMachineKind = localMachineKind;
+exports.resetLocalMachineKindCache = resetLocalMachineKindCache;
+exports.stampMachineIdentityContext = stampMachineIdentityContext;
 exports.suggestedShieldName = suggestedShieldName;
 const child_process_1 = require("child_process");
 const crypto = __importStar(require("crypto"));
@@ -229,6 +232,65 @@ function getMachineIdentity() {
     };
     return cached;
 }
+let cachedKind;
+/**
+ * Which KIND of fleet machine this process belongs to — the value the policy
+ * engine reads as `context.machineKind`, so a policy written for containers
+ * fires in containers and never on a laptop (and vice versa).
+ *
+ * Order: `FCD_MACHINE_KIND` (exported by ci-protect / workload-protect into
+ * the job/container env), then the ephemeral identity marker those commands
+ * write next to the credentials, then the FCD_DEVELOPER_NAME prefix older
+ * ephemeral stacks exported (`ci@…` / `workload@…`). Anything else is a
+ * workstation. Cheap: one env read, at most one small file read per process.
+ */
+function localMachineKind(env = process.env) {
+    if (cachedKind)
+        return cachedKind;
+    const explicit = (env.FCD_MACHINE_KIND || '').trim().toLowerCase();
+    if (explicit === 'ci' || explicit === 'workload')
+        return (cachedKind = explicit);
+    if ((env.FCD_MACHINE_ID || '').trim()) {
+        const dev = (env.FCD_DEVELOPER_NAME || '').trim().toLowerCase();
+        if (dev.startsWith('workload@'))
+            return (cachedKind = 'workload');
+        if (dev.startsWith('ci@'))
+            return (cachedKind = 'ci');
+    }
+    const marker = safe(() => fs.readFileSync(path.join(os.homedir(), '.fullcourtdefense', 'ephemeral-identity.json'), 'utf8'));
+    if (marker) {
+        try {
+            const kind = String(JSON.parse(marker).kind || '').toLowerCase();
+            if (kind === 'workload')
+                return (cachedKind = 'workload');
+            if (kind === 'pipeline' || kind === 'ci')
+                return (cachedKind = 'ci');
+        }
+        catch { /* malformed marker — treat as a workstation */ }
+    }
+    return (cachedKind = 'workstation');
+}
+/** Test seam: forget the cached kind (the marker / env changed). */
+function resetLocalMachineKindCache() {
+    cachedKind = undefined;
+}
+/**
+ * Stamp THIS machine's identity onto a policy-engine context — the single
+ * place the hook and the MCP gateway describe "who/where" to the engine, so
+ * `appliesTo.machineNames` / `appliesTo.machineKinds` / `developerName`
+ * targeting sees identical values on every enforcement point.
+ *
+ * `machineName` is the raw OS hostname (what admins pin in appliesTo);
+ * `machineKind` is what `localMachineKind()` resolved (workstation / ci /
+ * workload). `developerName` is only set when the caller resolved one.
+ */
+function stampMachineIdentityContext(context, developerName) {
+    if (developerName)
+        context.developerName = developerName;
+    context.machineName = safe(() => os.hostname()) || 'unknown-host';
+    context.machineKind = localMachineKind();
+    return context;
+}
 /** Suggested per-machine Shield name, e.g. `boazl@boaz-pc · Windows 11`. */
 function suggestedShieldName(identity = getMachineIdentity()) {
     return `${identity.developerName} · ${identity.osFriendly}`;

package/dist/telemetry.js

@@ -372,6 +372,12 @@ async function flushSpoolLocked(input) {
                         // the console reads root causes instead of asking the customer.
                         distress: input.distress,
                         lastCrash: input.lastCrash,
+                        // What kind of machine this really is (container / VM / physical,
+                        // runtime, hypervisor, cloud) from local firmware + /proc facts —
+                        // the console states the source of every event from THIS, never
+                        // from what an enrollment command claimed. Heartbeats only run
+                        // in the daemon / onboarding process, never on the hook path.
+                        hostRuntime: (await Promise.resolve().then(() => __importStar(require('./hostRuntime')))).getHostRuntime(),
                     }
                     : undefined,
                 events: batch,

package/dist/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.26.17"
+  "version": "1.27.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullcourtdefense-cli",
-  "version": "1.26.17",
+  "version": "1.27.0",
   "description": "Full Court Defense CLI — security scanning for AI agents from your terminal",
   "main": "dist/index.js",
   "bin": {