@compforge/harness-toolbox 0.5.5 → 0.6.1

package/README.md

@@ -152,23 +152,27 @@ selectorless Services and failed access raise KubernetesError.
 
 The resource path uses client-node kubeconfig authentication/TLS and bounded native JSON reads,
 not kubectl error text. Configure request timeout, concurrency and response bytes with the
-client's ResourceLimits constructor argument. Native exec uses the same root capacity/byte policy
+client's ResourceLimits constructor argument. Exec uses the same root capacity/byte policy
 with a separate slot pool; its per-call timeout defaults to that policy and covers queueing,
 authentication, upgrade and execution. Explicit per-call timeouts support longer commands.
 
-Exec requires `get pods/exec` permission for the WebSocket upgrade (kubectl/SPDY paths may use
-`create pods/exec`). It connects directly to the Pod exec WebSocket endpoint without a preliminary Pod GET or
-kubectl subprocess. Each command owns a stream session; failures are never retried or replayed.
-Kubeconfig controls authentication, TLS and proxy access. stdout/stderr and remote exit status
-remain separate; retained output and individual messages are bounded. Streaming callers may
-set `collectStdout: false` and enforce their own total byte budget. Root disposal cancels active
-and queued sessions. Protocol v4 is accepted for output-only commands; stdin requires v5 to
-close input without losing remaining output/status. Bun does not expose HTTP upgrade rejection
-status, so those failures retain an unknown connection error. Native exec with a kubeconfig
-proxy requires Node: Bun cannot reliably release proxy sockets or preserve TLS name overrides.
-It fails before opening a session on Bun; use Node or explicitly provide an Executor adapter.
-The transport never bypasses the proxy or TLS checks.
-Port-forward still uses kubectl.
+Output-only exec connects directly to the Pod exec WebSocket endpoint without a preliminary
+Pod GET and requires `get pods/exec`. Commands with explicit stdin (including empty input) use
+`kubectl exec -i`, which handles input EOF through SPDY/v5 on older and newer clusters. This
+path requires a compatible kubectl on the Host, Pod read permission and `create pods/exec`
+for SPDY (`get pods/exec` for WebSocket). The channel is selected before execution; failures
+are never retried or replayed by Toolbox. The result's `command` records the actual channel.
+Kubeconfig controls authentication, TLS and proxy access. Both paths share the root exec slot
+pool, deadline, retained-output byte limit and cancellation. stdout/stderr remain separate;
+native exec uses remote status and kubectl uses process exit status, retaining raw CLI stderr
+without guessing structured HTTP error kinds. Streaming callers may set `collectStdout: false`
+and enforce their own total byte budget; individual output chunks remain bounded. Root disposal
+cancels active and queued sessions and waits for the local kubectl process to exit.
+Output-only sessions accept v4/v5. Bun does not expose HTTP upgrade rejection status, so those
+failures retain an unknown connection error. Native exec with a kubeconfig proxy requires Node:
+Bun cannot reliably release proxy sockets or preserve TLS name overrides. This restriction does
+not apply to the kubectl stdin path. Neither path bypasses proxy or TLS checks.
+Port-forward also uses kubectl.
 See [the shared Workload model](../../../docs/workload.md).
 
 ```ts
@@ -465,3 +469,35 @@ IP literals and Kubernetes `service.namespace` names use the same API. There is
 implicit execution on the caller host or ICMP requirement. Network failure returns
 evidence; missing Python, execution failure and incomplete output throw. TLS success
 does not establish HTTP authorization, object access or application download policy.
+
+
+## Kubernetes environment and AppArmor admission
+
+`@compforge/harness-toolbox/kubernetes/environment-inspection` exports
+`inspectKubernetesEnvironment(access, instance, {timeoutMs, signal?})`. Pass an existing Common
+`WorkloadInstance`; the caller discovers and selects it (for example with `KubernetesClient.resolveWorkload`).
+The function reads that Pod, verifies its UID, reads `ip_forward` in the selected running container,
+and gets only its associated Node's `operatingSystem`, `osImage`, `kernelVersion` and `architecture`.
+It does not enumerate Nodes, select workloads or infer a host forwarding setting from the Pod namespace.
+
+```ts
+const result = await inspectKubernetesEnvironment({
+  resources: client.clusterResources(),
+  exec: client.exec.bind(client),
+}, selectedInstance, { timeoutMs: 5_000, signal });
+```
+
+Use a cluster-scoped resource view: Pod GET supplies its namespace explicitly; Node GET has none.
+The positive timeout is a shared request budget. Resource/exec adapters must honor the supplied timeout
+and cancellation signal. Node and forwarding reads retain independent successes and sanitized issues;
+`complete`, `partial` and `unavailable` describe coverage, not Service health. Cancellation throws.
+A missing or changed Pod UID prevents exec and Node attribution. A same-name replacement during the later
+name-addressed exec cannot be excluded atomically by Kubernetes; results describe a best-effort sample.
+
+`@compforge/harness-toolbox/kubernetes/apparmor` exports
+`probeAppArmorUnconfinedAdmission(executor, {namespace, serviceAccountName, image}, {timeoutMs, signal?})`.
+The caller supplies an authorized `Executor.run` channel. The function uses an explicit namespace and
+ServiceAccount impersonation with `create --dry-run=server`; it never persists a Pod. Results are
+`allowed`, `denied` (explicit AppArmor Unconfined admission rejection), or `unknown` (including generic
+RBAC, impersonation, timeout and transport failures). Acceptance does not verify Node runtime support.
+The caller owns permissions, Service semantics, scheduling and borrowed client/executor cleanup.

package/dist/{chunk-226wxr2s.js → chunk-7mc2jevr.js}

@@ -1,18 +1,18 @@
-import {
-  resolveWorkload
-} from "./chunk-d2y5ewbb.js";
 import {
   KubernetesResourceTransport
 } from "./chunk-361x998p.js";
+import {
+  resolveWorkload
+} from "./chunk-d2y5ewbb.js";
 import {
   KubernetesExecTransport
-} from "./chunk-0zcq74ep.js";
+} from "./chunk-dfpqr0r9.js";
 import {
   ServicePortForwarder
-} from "./chunk-0d8vs5q8.js";
+} from "./chunk-91xh8tsr.js";
 import {
   KubectlExecutor
-} from "./chunk-rq5fc007.js";
+} from "./chunk-evb5tj13.js";
 import {
   KubernetesError
 } from "./chunk-68zz17hs.js";

package/dist/{chunk-0d8vs5q8.js → chunk-91xh8tsr.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-6fnhzhdb.js";
 import {
   PortForwardScope
-} from "./chunk-mvkxs8d0.js";
+} from "./chunk-v9rcxg0e.js";
 
 // src/kubernetes/service-port-forward.ts
 class ServicePortForwarder {

package/dist/{chunk-0zcq74ep.js → chunk-dfpqr0r9.js}

@@ -1,6 +1,10 @@
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";
+import {
+  KubectlExecutor,
+  buildExecArgs
+} from "./chunk-evb5tj13.js";
 import {
   KubernetesError,
   kubernetesHttpError
@@ -10,29 +14,28 @@ import {
 import { KubeConfig } from "@kubernetes/client-node";
 import WebSocket from "ws";
 class KubernetesExecTransport {
+  connection;
   signal;
   limits;
   #config = new KubeConfig;
   #capacity;
   #server;
-  constructor(options, signal, limits) {
+  constructor(connection, signal, limits) {
+    this.connection = connection;
     this.signal = signal;
     this.limits = limits;
     if (!Object.values(limits).every((value) => Number.isSafeInteger(value) && value > 0)) {
       throw new KubernetesError("Exec limits must be positive integers", { kind: "invalid_argument" });
     }
-    if (options.kubeconfig)
-      this.#config.loadFromFile(options.kubeconfig);
+    if (connection.kubeconfig)
+      this.#config.loadFromFile(connection.kubeconfig);
     else
       this.#config.loadFromDefault();
-    if (options.context)
-      this.#config.setCurrentContext(options.context);
+    if (connection.context)
+      this.#config.setCurrentContext(connection.context);
     const cluster = this.#config.getCurrentCluster();
     if (!cluster)
       throw new KubernetesError("Kubernetes context has no cluster", { kind: "invalid_argument" });
-    if (process.versions.bun && cluster.proxyUrl) {
-      throw new KubernetesError("Native exec through a kubeconfig proxy requires a Node host", { kind: "unsupported_operation" });
-    }
     this.#server = cluster.server.replace(/\/$/, "");
     if (new URL(cluster.server).protocol === "http:")
       this.#config.clusters = this.#config.clusters.map((item) => item === cluster ? { ...item, skipTLSVerify: true } : item);
@@ -49,17 +52,71 @@ class KubernetesExecTransport {
     const signal = AbortSignal.any([caller, deadline.signal]);
     const timer = setTimeout(() => deadline.abort(), timeoutMs);
     try {
-      return await this.#capacity.run(() => this.#session(namespace, target, command, options, signal, started, deadline.signal), signal);
+      return await this.#capacity.run(() => options.stdin === undefined ? this.#session(namespace, target, command, options, signal, started, deadline.signal) : this.#stdinSession(namespace, target, command, options, signal, started), signal);
     } catch (error) {
       if (caller.aborted)
         throw caller.reason;
-      if (deadline.signal.aborted)
-        return this.#result(namespace, target, command, started, null, "", "Exec deadline exceeded", true);
+      if (deadline.signal.aborted) {
+        const result = this.#result(namespace, target, command, started, null, "", "Exec deadline exceeded", true);
+        if (options.stdin !== undefined)
+          result.command = buildExecArgs({ ...this.connection, namespace }, target, command, true);
+        return result;
+      }
       throw error;
     } finally {
       clearTimeout(timer);
     }
   }
+  async#stdinSession(namespace, target, command, options, signal, started) {
+    const controller = new AbortController;
+    const combined = AbortSignal.any([signal, controller.signal]);
+    let retained = 0;
+    let stdout = "";
+    let failure;
+    const guard = (action) => {
+      if (combined.aborted)
+        return;
+      try {
+        action();
+      } catch (cause) {
+        failure = cause;
+        controller.abort(cause);
+        throw cause;
+      }
+    };
+    const count = (size, retain) => {
+      if (retain)
+        retained += size;
+      if (size > this.limits.maxBytes || retained > this.limits.maxBytes) {
+        throw new KubernetesError(`Kubernetes exec ${namespace}/${target.pod} output exceeds ${this.limits.maxBytes} bytes`, { kind: "limit_exceeded" });
+      }
+    };
+    const executor = new KubectlExecutor({ ...this.connection, namespace });
+    const result = await executor.exec(target, command, {
+      ...options,
+      signal: combined,
+      timeoutMs: Math.max(1, (options.timeoutMs ?? this.limits.timeoutMs) - (performance.now() - started)),
+      collectStdout: false,
+      onStdoutBytes: (bytes) => guard(() => {
+        count(bytes.length, options.collectStdout !== false);
+        options.onStdoutBytes?.(bytes);
+      }),
+      onStdout: (text) => guard(() => {
+        if (options.collectStdout !== false)
+          stdout += text;
+        options.onStdout?.(text);
+      }),
+      onStderr: (text) => guard(() => {
+        count(Buffer.byteLength(text), true);
+        options.onStderr?.(text);
+      })
+    });
+    if (controller.signal.aborted)
+      throw failure;
+    if (signal.aborted)
+      throw signal.reason;
+    return { ...result, stdout, durationMs: performance.now() - started };
+  }
   #result(namespace, target, command, started, exitCode, stdout, stderr, timedOut = false) {
     return {
       ok: exitCode === 0 && !timedOut,
@@ -81,10 +138,12 @@ class KubernetesExecTransport {
     };
   }
   #session(namespace, target, command, options, signal, started, deadline) {
+    if (process.versions.bun && this.#config.getCurrentCluster()?.proxyUrl) {
+      throw new KubernetesError("Native exec through a kubeconfig proxy requires a Node host", { kind: "unsupported_operation" });
+    }
     return new Promise((resolve, reject) => {
       let socket;
       let agent;
-      let input;
       let settled = false;
       let stdout = "", stderr = "", retained = 0;
       const outDecoder = new TextDecoder, errDecoder = new TextDecoder;
@@ -95,7 +154,6 @@ class KubernetesExecTransport {
         signal.removeEventListener("abort", abort);
         socket?.terminate();
         agent?.destroy();
-        input?.cancel().catch(() => {});
         const tail = outDecoder.decode(), errTail = errDecoder.decode();
         if (options.collectStdout !== false)
           stdout += tail;
@@ -140,11 +198,11 @@ Exec deadline exceeded`;
           url.searchParams.append("command", arg);
         url.searchParams.set("stdout", "true");
         url.searchParams.set("stderr", "true");
-        url.searchParams.set("stdin", String(options.stdin !== undefined));
+        url.searchParams.set("stdin", "false");
         url.searchParams.set("tty", "false");
         if (target.container)
           url.searchParams.set("container", target.container);
-        socket = new WebSocket(url, options.stdin === undefined ? ["v5.channel.k8s.io", "v4.channel.k8s.io"] : ["v5.channel.k8s.io"], { ...request, ...process.versions.bun ? { tls: {
+        socket = new WebSocket(url, ["v5.channel.k8s.io", "v4.channel.k8s.io"], { ...request, ...process.versions.bun ? { tls: {
           ca: request.ca,
           cert: request.cert,
           key: request.key,
@@ -225,37 +283,6 @@ Exec deadline exceeded`;
             fail("invalid_response", error);
           }
         });
-        socket.on("open", () => {
-          if (options.stdin === undefined || settled)
-            return;
-          const send = (bytes) => new Promise((done, failed) => {
-            if (settled) {
-              failed(new Error("Exec closed"));
-              return;
-            }
-            socket.send(Buffer.concat([Buffer.from([0]), bytes]), (error) => error ? failed(error) : done());
-          });
-          (async () => {
-            const stdin = options.stdin;
-            if (typeof stdin === "string" || stdin instanceof Uint8Array)
-              await send(typeof stdin === "string" ? new TextEncoder().encode(stdin) : stdin);
-            else {
-              const reader = stdin.getReader();
-              input = reader;
-              while (!settled) {
-                const chunk = await reader.read();
-                if (chunk.done)
-                  break;
-                await send(chunk.value);
-              }
-            }
-            if (!settled)
-              socket.send(Buffer.from([255, 0]));
-          })().catch((error) => {
-            if (!settled)
-              fail("connection_failed", error);
-          });
-        });
       }).catch((error) => {
         if (!settled)
           fail("connection_failed", error);

package/dist/{chunk-rq5fc007.js → chunk-evb5tj13.js}

@@ -68,24 +68,25 @@ async function runArgv(argv, opts) {
   let aborted = false;
   const abort = () => {
     aborted = true;
-    proc.kill();
+    proc.kill("SIGKILL");
   };
   const timer = setTimeout(() => {
     timedOut = true;
-    proc.kill();
+    proc.kill("SIGKILL");
   }, timeoutMs);
   if (opts?.signal?.aborted)
     abort();
   else
     opts?.signal?.addEventListener("abort", abort, { once: true });
+  const outputs = [
+    readOutput(proc.stdout, opts?.onStdout, opts?.onStdoutBytes, opts?.collectStdout ?? true),
+    readOutput(proc.stderr, opts?.onStderr),
+    proc.exited
+  ];
   try {
-    const [stdout, stderr, exitCode] = await Promise.all([
-      readOutput(proc.stdout, opts?.onStdout, opts?.onStdoutBytes, opts?.collectStdout ?? true),
-      readOutput(proc.stderr, opts?.onStderr),
-      proc.exited
-    ]);
+    const [stdout, stderr, exitCode] = await Promise.all(outputs);
     return {
-      ok: exitCode === 0 && !timedOut,
+      ok: exitCode === 0 && !timedOut && !aborted,
       exitCode,
       stdout,
       stderr: timedOut ? `${stderr}
@@ -96,6 +97,8 @@ async function runArgv(argv, opts) {
       command: argv
     };
   } catch (err) {
+    proc.kill("SIGKILL");
+    await Promise.allSettled(outputs);
     return {
       ok: false,
       exitCode: null,

package/dist/{chunk-9d0ph5km.js → chunk-s7a3fqzc.js}

@@ -3,10 +3,10 @@ import {
 } from "./chunk-ssj93brx.js";
 import {
   startPortForward
-} from "./chunk-mvkxs8d0.js";
+} from "./chunk-v9rcxg0e.js";
 import {
   KubectlExecutor
-} from "./chunk-rq5fc007.js";
+} from "./chunk-evb5tj13.js";
 import {
   Transport
 } from "./chunk-6rcyw5ek.js";

package/dist/{chunk-mvkxs8d0.js → chunk-v9rcxg0e.js}

@@ -1,6 +1,6 @@
 import {
   buildKubectlArgs
-} from "./chunk-rq5fc007.js";
+} from "./chunk-evb5tj13.js";
 import {
   spawnProcess
 } from "./chunk-9shz0bw1.js";

package/dist/{chunk-47x0r2kr.js → chunk-xv3nn2vd.js}

@@ -1,9 +1,9 @@
 import {
   ServicePortForwarder
-} from "./chunk-0d8vs5q8.js";
+} from "./chunk-91xh8tsr.js";
 import {
   KubectlExecutor
-} from "./chunk-rq5fc007.js";
+} from "./chunk-evb5tj13.js";
 import {
   Transport
 } from "./chunk-6rcyw5ek.js";

package/dist/http/client.js

@@ -2,16 +2,16 @@ import {
   HttpClient
 } from "../chunk-81agmerq.js";
 import"../chunk-ps7f1x05.js";
-import"../chunk-9d0ph5km.js";
+import"../chunk-s7a3fqzc.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-c2b2jwm4.js";
 import"../chunk-ssj93brx.js";
-import"../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/dist/http/index.js

@@ -2,16 +2,16 @@ import {
   HttpClient
 } from "../chunk-81agmerq.js";
 import"../chunk-ps7f1x05.js";
-import"../chunk-9d0ph5km.js";
+import"../chunk-s7a3fqzc.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-c2b2jwm4.js";
 import"../chunk-ssj93brx.js";
-import"../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/dist/kubernetes/apparmor.d.ts

@@ -0,0 +1,24 @@
+import { type ErrorKind } from "../errors";
+import type { Executor } from "./executor";
+export interface AppArmorUnconfinedAdmissionInput {
+    namespace: string;
+    serviceAccountName: string;
+    image: string;
+}
+export interface AppArmorUnconfinedAdmissionResult {
+    target: AppArmorUnconfinedAdmissionInput;
+    observedAt: string;
+    status: "allowed" | "denied" | "unknown";
+    reason?: string;
+    errorKind?: ErrorKind;
+}
+/**
+ * @spec Probe AppArmor Unconfined admission as the supplied ServiceAccount using server-side dry-run only.
+ * @rule Admission acceptance does not prove Node support. Generic RBAC/auth/transport failures remain unknown.
+ * @rule Caller owns target selection, authorization and executor lifecycle; no workload or Service discovery occurs.
+ * @link docs/toolbox.md
+ */
+export declare function probeAppArmorUnconfinedAdmission(executor: Pick<Executor, "run">, input: AppArmorUnconfinedAdmissionInput, options: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<AppArmorUnconfinedAdmissionResult>;

package/dist/kubernetes/apparmor.js

@@ -0,0 +1,60 @@
+import {
+  KubernetesError,
+  kubernetesCommandError
+} from "../chunk-68zz17hs.js";
+
+// src/kubernetes/apparmor.ts
+async function probeAppArmorUnconfinedAdmission(executor, input, options) {
+  if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || !input.image.trim() || !/^[a-z0-9][a-z0-9-]*$/.test(input.namespace) || !/^[a-z0-9][a-z0-9.-]*$/.test(input.serviceAccountName)) {
+    throw new KubernetesError("AppArmor admission requires namespace, ServiceAccount, image and positive timeout", { kind: "invalid_argument" });
+  }
+  options.signal?.throwIfAborted();
+  const result = { target: { ...input }, observedAt: new Date().toISOString(), status: "unknown" };
+  const manifest = {
+    apiVersion: "v1",
+    kind: "Pod",
+    metadata: { generateName: "apparmor-unconfined-probe-", namespace: input.namespace },
+    spec: { serviceAccountName: input.serviceAccountName, restartPolicy: "Never", containers: [{
+      name: "probe",
+      image: input.image,
+      securityContext: {
+        appArmorProfile: { type: "Unconfined" },
+        allowPrivilegeEscalation: false,
+        capabilities: { drop: ["ALL"] },
+        runAsNonRoot: true,
+        runAsUser: 65532,
+        seccompProfile: { type: "RuntimeDefault" }
+      }
+    }] }
+  };
+  try {
+    const execution = await executor.run([
+      "create",
+      "-f",
+      "-",
+      "--dry-run=server",
+      "-o",
+      "json",
+      "--namespace",
+      input.namespace,
+      "--as",
+      `system:serviceaccount:${input.namespace}:${input.serviceAccountName}`
+    ], { ...options, stdin: JSON.stringify(manifest) });
+    options.signal?.throwIfAborted();
+    if (execution.ok)
+      return { ...result, status: "allowed" };
+    const output = `${execution.stderr}
+${execution.stdout}`;
+    if (!execution.timedOut && /apparmor/i.test(output) && /unconfined/i.test(output) && /(?:admission|violates\s+podsecurity)/i.test(output) && /(denied|forbidden|violates\s+podsecurity)/i.test(output)) {
+      return { ...result, status: "denied", reason: "Admission rejected AppArmor Unconfined" };
+    }
+    throw kubernetesCommandError(execution);
+  } catch (error) {
+    options.signal?.throwIfAborted();
+    const kind = error instanceof KubernetesError ? error.kind : "operation_failed";
+    return { ...result, errorKind: kind, reason: `AppArmor admission could not be determined: ${kind}` };
+  }
+}
+export {
+  probeAppArmorUnconfinedAdmission
+};

package/dist/kubernetes/client.js

@@ -1,17 +1,17 @@
 import {
   KubernetesClient
-} from "../chunk-226wxr2s.js";
-import"../chunk-d2y5ewbb.js";
+} from "../chunk-7mc2jevr.js";
 import"../chunk-361x998p.js";
+import"../chunk-d2y5ewbb.js";
 import"../chunk-jt8fn3wg.js";
-import"../chunk-0zcq74ep.js";
+import"../chunk-dfpqr0r9.js";
 import"../chunk-a9htb6cr.js";
 import"../chunk-v3hxvnrc.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-68zz17hs.js";
 export {

package/dist/kubernetes/environment-inspection.d.ts

@@ -0,0 +1,36 @@
+import type { WorkloadInstance } from "@compforge/harness-common";
+import { type ErrorKind } from "../errors";
+import type { KubernetesClient } from "./client";
+import type { ResourceAccess } from "./resources";
+export interface KubernetesEnvironmentAccess {
+    /** Explicit cluster-scoped resource view; Pod requests supply their namespace, Node requests do not. */
+    resources: Pick<ResourceAccess, "get">;
+    /** Borrow the caller's authorized exec channel; this function never creates or disposes a client. */
+    exec: KubernetesClient["exec"];
+}
+export interface KubernetesEnvironmentIssue {
+    source: "pod" | "pod.ip_forward" | "node" | `node.${string}`;
+    kind: ErrorKind;
+    message: string;
+}
+export interface KubernetesEnvironmentInspection {
+    instance: WorkloadInstance;
+    observedAt: string;
+    status: "complete" | "partial" | "unavailable";
+    /** Value in the sampled Pod's network namespace, not proof of the host setting. */
+    podIpForward?: 0 | 1;
+    container?: string;
+    nodeName?: string;
+    nodeInfo: Partial<Record<"operatingSystem" | "osImage" | "kernelVersion" | "architecture", string>>;
+    issues: KubernetesEnvironmentIssue[];
+}
+/**
+ * @spec Inspect only the supplied WorkloadInstance and its Node. Discovery and sampling belong to the caller.
+ * @rule Reject a Pod already replaced at the identity read; later name-addressed exec is not atomic with that read.
+ * @rule ip_forward is Pod-netns scoped; OS metadata comes from Node status.nodeInfo, never the container image.
+ * @link docs/toolbox.md
+ */
+export declare function inspectKubernetesEnvironment(access: KubernetesEnvironmentAccess, instance: WorkloadInstance, options: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<KubernetesEnvironmentInspection>;

package/dist/kubernetes/environment-inspection.js

@@ -0,0 +1,107 @@
+import {
+  KubernetesError
+} from "../chunk-68zz17hs.js";
+
+// src/kubernetes/environment-inspection.ts
+function object(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function text(value) {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+function issue(source, error) {
+  const kind = error instanceof KubernetesError ? error.kind : "operation_failed";
+  return { source, kind, message: `Kubernetes environment read failed: ${kind}` };
+}
+async function inspectKubernetesEnvironment(access, instance, options) {
+  if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || instance.platform !== "kubernetes" || [instance.environment, instance.workload, instance.namespace, instance.pod, instance.uid].some((value) => !value?.trim())) {
+    throw new KubernetesError("Environment inspection requires a WorkloadInstance and positive timeout", { kind: "invalid_argument" });
+  }
+  const deadline = performance.now() + options.timeoutMs;
+  const request = () => {
+    options.signal?.throwIfAborted();
+    const timeoutMs = Math.ceil(deadline - performance.now());
+    if (timeoutMs <= 0)
+      throw new KubernetesError("Environment inspection budget exhausted", { kind: "timeout" });
+    return { timeoutMs, signal: options.signal };
+  };
+  const result = {
+    instance: { ...instance },
+    observedAt: new Date().toISOString(),
+    status: "unavailable",
+    nodeInfo: {},
+    issues: []
+  };
+  let pod;
+  try {
+    pod = await access.resources.get({ apiVersion: "v1", resource: "pods", namespace: instance.namespace, name: instance.pod }, request());
+    options.signal?.throwIfAborted();
+    const meta = object(pod.metadata);
+    if (meta.uid !== instance.uid || meta.name !== instance.pod || meta.namespace !== instance.namespace) {
+      throw new KubernetesError("Pod identity changed or is missing", { kind: "invalid_response" });
+    }
+  } catch (error) {
+    options.signal?.throwIfAborted();
+    result.issues.push(issue("pod", error));
+    return result;
+  }
+  const spec = object(pod.spec), status = object(pod.status);
+  const containers = Array.isArray(spec.containers) ? spec.containers.map(object) : [];
+  const container = instance.container ? containers.find((item) => item.name === instance.container) : containers.length === 1 ? containers[0] : undefined;
+  result.container = text(container?.name);
+  result.nodeName = text(spec.nodeName);
+  const [forwardingIssues, nodeIssues] = await Promise.all([
+    (async () => {
+      try {
+        if (!result.container)
+          throw new KubernetesError("Target container is absent or ambiguous", { kind: "invalid_argument" });
+        const states = Array.isArray(status.containerStatuses) ? status.containerStatuses.map(object) : [];
+        if (status.phase !== "Running" || !object(states.find((item) => item.name === result.container)?.state).running) {
+          throw new KubernetesError("Target container is not running", { kind: "unsupported_operation" });
+        }
+        const execution = await access.exec(instance.namespace, { pod: instance.pod, container: result.container }, ["cat", "/proc/sys/net/ipv4/ip_forward"], request());
+        options.signal?.throwIfAborted();
+        if (!execution.ok)
+          throw new KubernetesError("Could not read ip_forward", { kind: execution.timedOut ? "timeout" : "operation_failed" });
+        const value = execution.stdout.trim();
+        if (value !== "0" && value !== "1")
+          throw new KubernetesError("Invalid ip_forward response", { kind: "invalid_response" });
+        result.podIpForward = value === "1" ? 1 : 0;
+        return [];
+      } catch (error) {
+        options.signal?.throwIfAborted();
+        return [issue("pod.ip_forward", error)];
+      }
+    })(),
+    (async () => {
+      try {
+        if (!result.nodeName)
+          throw new KubernetesError("Pod nodeName is absent", { kind: "resource_not_found" });
+        const node = await access.resources.get({ apiVersion: "v1", resource: "nodes", name: result.nodeName }, request());
+        options.signal?.throwIfAborted();
+        if (node.metadata?.name !== result.nodeName)
+          throw new KubernetesError("Node identity is missing or mismatched", { kind: "invalid_response" });
+        const info = object(object(node.status).nodeInfo);
+        const issues = [];
+        for (const field of ["operatingSystem", "osImage", "kernelVersion", "architecture"]) {
+          const value = text(info[field]);
+          if (value)
+            result.nodeInfo[field] = value;
+          else
+            issues.push({ source: `node.${field}`, kind: "invalid_response", message: `Node status.nodeInfo.${field} is missing` });
+        }
+        return issues;
+      } catch (error) {
+        options.signal?.throwIfAborted();
+        return [issue("node", error)];
+      }
+    })()
+  ]);
+  options.signal?.throwIfAborted();
+  result.issues.push(...forwardingIssues, ...nodeIssues);
+  result.status = !result.issues.length ? "complete" : result.podIpForward !== undefined || Object.keys(result.nodeInfo).length ? "partial" : "unavailable";
+  return result;
+}
+export {
+  inspectKubernetesEnvironment
+};

package/dist/kubernetes/environment.js

@@ -1,19 +1,19 @@
 import {
   KubernetesClient
-} from "../chunk-226wxr2s.js";
-import"../chunk-d2y5ewbb.js";
+} from "../chunk-7mc2jevr.js";
 import"../chunk-361x998p.js";
+import"../chunk-d2y5ewbb.js";
 import"../chunk-jt8fn3wg.js";
-import"../chunk-0zcq74ep.js";
+import"../chunk-dfpqr0r9.js";
 import {
   clientKey
 } from "../chunk-a9htb6cr.js";
 import"../chunk-v3hxvnrc.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-68zz17hs.js";
 

package/dist/kubernetes/exec-transport.d.ts

@@ -1,4 +1,4 @@
-import type { ExecTarget, ExecResult, RunOptions } from "./executor";
+import { type ExecTarget, type ExecResult, type RunOptions } from "./executor";
 import type { KubernetesConnectionOptions } from "./resource-transport";
 export interface KubernetesExecLimits {
     timeoutMs: number;
@@ -12,8 +12,9 @@ export interface KubernetesExecLimits {
  */
 export declare class KubernetesExecTransport {
     #private;
+    private readonly connection;
     private readonly signal;
     private readonly limits;
-    constructor(options: KubernetesConnectionOptions, signal: AbortSignal, limits: KubernetesExecLimits);
+    constructor(connection: KubernetesConnectionOptions, signal: AbortSignal, limits: KubernetesExecLimits);
     exec(namespace: string, target: ExecTarget, command: string[], options?: RunOptions): Promise<ExecResult>;
 }

package/dist/kubernetes/exec-transport.js

@@ -1,7 +1,9 @@
 import {
   KubernetesExecTransport
-} from "../chunk-0zcq74ep.js";
+} from "../chunk-dfpqr0r9.js";
 import"../chunk-v3hxvnrc.js";
+import"../chunk-evb5tj13.js";
+import"../chunk-9shz0bw1.js";
 import"../chunk-68zz17hs.js";
 export {
   KubernetesExecTransport

package/dist/kubernetes/executor.js

@@ -3,7 +3,7 @@ import {
   buildExecArgs,
   buildKubectlArgs,
   runArgv
-} from "../chunk-rq5fc007.js";
+} from "../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 export {
   runArgv,

package/dist/kubernetes/pod-log-client.js

@@ -1,9 +1,9 @@
 import {
   PodLogClient
-} from "../chunk-mnad4zkp.js";
+} from "../chunk-010339ga.js";
 import"../chunk-8nm9f0hh.js";
-import"../chunk-mp88s7r7.js";
 import"../chunk-1vfwvgkj.js";
+import"../chunk-mp88s7r7.js";
 import"../chunk-a9htb6cr.js";
 import"../chunk-v3hxvnrc.js";
 export {

package/dist/kubernetes/pod-log-datasource.js

@@ -1,9 +1,9 @@
 import {
   PodLogClient
-} from "../chunk-mnad4zkp.js";
+} from "../chunk-010339ga.js";
 import"../chunk-8nm9f0hh.js";
-import"../chunk-mp88s7r7.js";
 import"../chunk-1vfwvgkj.js";
+import"../chunk-mp88s7r7.js";
 import"../chunk-a9htb6cr.js";
 import {
   clientKey

package/dist/kubernetes/port-forward.js

@@ -1,8 +1,8 @@
 import {
   PortForwardScope,
   startPortForward
-} from "../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+} from "../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 export {
   startPortForward,

package/dist/kubernetes/service-port-forward.js

@@ -1,10 +1,10 @@
 import {
   ServicePortForwarder
-} from "../chunk-0d8vs5q8.js";
+} from "../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 export {
   ServicePortForwarder

package/dist/mysql/client.js

@@ -7,15 +7,15 @@ import"../chunk-m91t44jh.js";
 import"../chunk-db4an9td.js";
 import"../chunk-835fssgz.js";
 import"../chunk-ps7f1x05.js";
-import"../chunk-9d0ph5km.js";
+import"../chunk-s7a3fqzc.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-ssj93brx.js";
-import"../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/dist/mysql/index.js

@@ -19,15 +19,15 @@ import {
 } from "../chunk-1gyshqd9.js";
 import"../chunk-835fssgz.js";
 import"../chunk-ps7f1x05.js";
-import"../chunk-9d0ph5km.js";
+import"../chunk-s7a3fqzc.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-ssj93brx.js";
-import"../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/dist/opensearch/client.js

@@ -7,14 +7,14 @@ import {
   openSearchServername
 } from "../chunk-6dfcndra.js";
 import"../chunk-ps7f1x05.js";
-import"../chunk-9d0ph5km.js";
+import"../chunk-s7a3fqzc.js";
 import"../chunk-ssj93brx.js";
-import"../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/dist/opensearch/index.js

@@ -14,14 +14,14 @@ import {
   openSearchServername
 } from "../chunk-6dfcndra.js";
 import"../chunk-ps7f1x05.js";
-import"../chunk-9d0ph5km.js";
+import"../chunk-s7a3fqzc.js";
 import"../chunk-ssj93brx.js";
-import"../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/dist/redis/client.js

@@ -7,14 +7,14 @@ import {
 } from "../chunk-ywk81p8a.js";
 import"../chunk-5tbzf9wd.js";
 import"../chunk-ps7f1x05.js";
-import"../chunk-9d0ph5km.js";
+import"../chunk-s7a3fqzc.js";
 import"../chunk-ssj93brx.js";
-import"../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/dist/redis/index.js

@@ -13,14 +13,14 @@ import {
   discoverRedisTopology
 } from "../chunk-5tbzf9wd.js";
 import"../chunk-ps7f1x05.js";
-import"../chunk-9d0ph5km.js";
+import"../chunk-s7a3fqzc.js";
 import"../chunk-ssj93brx.js";
-import"../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/dist/s3/client.js

@@ -2,17 +2,17 @@ import {
   S3Client
 } from "../chunk-mj6ckk1g.js";
 import"../chunk-ps7f1x05.js";
-import"../chunk-9d0ph5km.js";
+import"../chunk-s7a3fqzc.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-z8e1ckkq.js";
 import"../chunk-c2b2jwm4.js";
 import"../chunk-ssj93brx.js";
-import"../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/dist/s3/datasource.js

@@ -4,17 +4,17 @@ import {
 import"../chunk-z5pm2emz.js";
 import"../chunk-mj6ckk1g.js";
 import"../chunk-ps7f1x05.js";
-import"../chunk-9d0ph5km.js";
+import"../chunk-s7a3fqzc.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-z8e1ckkq.js";
 import"../chunk-c2b2jwm4.js";
 import"../chunk-ssj93brx.js";
-import"../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/dist/s3/index.js

@@ -6,17 +6,17 @@ import {
   S3Client
 } from "../chunk-mj6ckk1g.js";
 import"../chunk-ps7f1x05.js";
-import"../chunk-9d0ph5km.js";
+import"../chunk-s7a3fqzc.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-z8e1ckkq.js";
 import"../chunk-c2b2jwm4.js";
 import"../chunk-ssj93brx.js";
-import"../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+import"../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/dist/transport/index.js

@@ -6,16 +6,16 @@ import {
 } from "../chunk-ps7f1x05.js";
 import {
   PodRelayTransport
-} from "../chunk-9d0ph5km.js";
+} from "../chunk-s7a3fqzc.js";
 import"../chunk-ssj93brx.js";
 import {
   ServicePortForwardTransport
-} from "../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+} from "../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import {
   Transport

package/dist/transport/pod-relay.js

@@ -1,9 +1,9 @@
 import {
   PodRelayTransport
-} from "../chunk-9d0ph5km.js";
+} from "../chunk-s7a3fqzc.js";
 import"../chunk-ssj93brx.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/dist/transport/service-port-forward.js

@@ -1,11 +1,11 @@
 import {
   ServicePortForwardTransport
-} from "../chunk-47x0r2kr.js";
-import"../chunk-0d8vs5q8.js";
+} from "../chunk-xv3nn2vd.js";
+import"../chunk-91xh8tsr.js";
 import"../chunk-xgnz10sr.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-mvkxs8d0.js";
-import"../chunk-rq5fc007.js";
+import"../chunk-v9rcxg0e.js";
+import"../chunk-evb5tj13.js";
 import"../chunk-9shz0bw1.js";
 import"../chunk-6rcyw5ek.js";
 import"../chunk-9f9dsjnr.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.5.5",
+  "version": "0.6.1",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -112,7 +112,7 @@
   ],
   "dependencies": {
     "@aws-sdk/client-s3": "3.1133.0",
-    "@compforge/harness-common": "0.5.13",
+    "@compforge/harness-common": "0.6.0",
     "@kubernetes/client-node": "1.4.0",
     "@opensearch-project/opensearch": "3.6.0",
     "@redis/client": "6.1.0",

package/dist/{chunk-mnad4zkp.js → chunk-010339ga.js}

@@ -2,12 +2,12 @@ import {
   PodLogByteBudget,
   runPodLogCapturePlan
 } from "./chunk-8nm9f0hh.js";
-import {
-  logTimestampNanos
-} from "./chunk-mp88s7r7.js";
 import {
   LogCaptureFile
 } from "./chunk-1vfwvgkj.js";
+import {
+  logTimestampNanos
+} from "./chunk-mp88s7r7.js";
 import {
   clientKey
 } from "./chunk-a9htb6cr.js";