Inspect a Cohesix Queen

Use this to answer “what system am I looking at, what is visible, and what is still unknown?” It does not establish GPU execution or release acceptance.

Select the installation and backend

On macOS or Linux, use the matching installed host bundle, or tools built for that host from one source revision. The read-only workflow is the same on both; use each host’s own executable and Python environment. Check the host OS, architecture, bundle version and command availability before connecting. If a binary or Python package does not match, explain the mismatch and point to the correct host bundle or matching Python environment; keep target inspection read-only while setup is unresolved. Set COH_BIN to the absolute executable directory of the verified installation: the extracted bundle’s bin/, the installed native package’s bin/, or a matching source build. For the published 1.2.0 native packages, the installed paths are /Library/Application Support/Cohesix/bin on macOS and /usr/lib/cohesix/bin on Ubuntu ARM64; verify the actual receipt before using either. The commands use absolute paths and need no bundle-root working directory. Examples use Bash; Python needs 3.11+ and the matching installed cohesix package in its environment. Check "$COH_BIN/coh" --help and "$COH_BIN/cohsh" --help. If a command is missing, use the matching bundled guide; do not mix in a newer binary. Host tools owns installation, credentials and topology.

For source-oriented links in this skill, use the corresponding local file at your selected revision, or replace main in the URL with its commit/tag. Absolute web links also work when this skill folder is copied out of the repo. Do not assume main describes an older release.

First useful read without a target

"$COH_BIN/cohsh" --transport mock --role queen

At coh> enter these commands individually:

ls /
cat /proc/boot
cat /proc/schedule/summary
cat /proc/lease/summary
quit

Expect a namespace and bounded model records. Label the result mock, with no live Queen contacted. Missing model paths mean unavailable, not live failure. This tour issues no control writes. Mock is not a general sandbox: Python mock constructors write local files, and coh run --mock can still execute host code.

For Python-only exploration, this snippet explicitly chooses fresh temporary model storage, reads it, then removes only that storage:

from tempfile import TemporaryDirectory
from cohesix import MockBackend

with TemporaryDirectory(prefix="cohesix-inspect-") as directory:
    backend = MockBackend(root=directory)
    print("source=host-model", backend.list_dir("/"))
    print(backend.read_file("/gpu/GPU-0/info", 1024).decode("utf-8"))

The mock GPU is synthetic. Do not use environment auto-selection for an unfamiliar deployment: a stale mock or mount variable can mask the intended REST backend. See Python support for selection precedence.

Inspect an already-configured live Queen

Obtain the gateway URL, intended target identity/profile and read credentials from the operator. Non-public reads need the gateway request-auth token and a delegated ticket with Read or ReadWrite scope for the requested paths and finite quota. Do not mint a broader ticket or enable --read-compatibility. Use the existing gateway: it owns the single target TCP console. Do not start a second gateway or direct TCP client, disconnect an owner, change network settings or request elevated credentials to make inspection work.

: "${COH_REST_URL:?set the operator-supplied gateway base URL}"
: "${COH_READ_HEADERS:?set a private operator-provisioned HTTP header file}"
curl --header "@$COH_READ_HEADERS" --fail-with-body --silent --show-error --max-time 15 \
  "$COH_REST_URL/v1/meta/status"
curl --header "@$COH_READ_HEADERS" --fail-with-body --silent --show-error --max-time 15 \
  "$COH_REST_URL/v1/meta/bounds"
curl --header "@$COH_READ_HEADERS" --fail-with-body --silent --show-error --max-time 15 --get \
  --data-urlencode 'path=/proc/boot' --data-urlencode 'max_bytes=1024' \
  "$COH_REST_URL/v1/fs/cat"

COH_READ_HEADERS contains two header lines: Authorization: Bearer TOKEN and x-cohesix-ticket: TICKET, with real operator-provisioned values, not those placeholders. Keep this file private; do not print it or put secrets on argv.

Require connected: true and a live console backend, then compare target /proc/boot identity with the operator’s expected image/profile. Gateway bounds describe compiled host policy, not target identity. Check any cache/freshness metadata; one snapshot does not prove continuing progress. Require filesystem JSON status: "OK" and terminal end: true; HTTP 200 alone can carry a target error. A refused or timed-out read remains unknown. A connected mock gateway is still a model. REST reads remain bounded by both delegated read scope and the gateway’s upstream role; read credentials are not permission to mutate. Use the operator’s secured endpoint/tunnel; do not send secrets to an unverified URL.

For CLI/Python reads, have the operator load HIVE_GATEWAY_REQUEST_AUTH_TOKEN and COH_REST_TICKET into the protected process environment (the latter is the actual delegated ticket for Python, not a file reference). Avoid shell tracing and conflicting credential aliases. Open the same namespace tour:

: "${HIVE_GATEWAY_REQUEST_AUTH_TOKEN:?load the request-auth credential securely}"
: "${COH_REST_TICKET:?load the delegated read ticket securely}"
"$COH_BIN/cohsh" --transport rest --rest-url "$COH_REST_URL" --role queen

Run the read commands above, then quit. --role queen does not elevate the gateway’s upstream authority. On source versions with inspect, a bounded summary is available via "$COH_BIN/coh" inspect --rest-url "$COH_REST_URL" --json.

Equivalent explicit Python read (no control write):

import os
from cohesix import RestBackend

backend = RestBackend(
    base_url=os.environ["COH_REST_URL"],
    request_auth_token=os.environ["HIVE_GATEWAY_REQUEST_AUTH_TOKEN"],
    delegated_ticket=os.environ["COH_REST_TICKET"],
    max_attempts=1,
)
print(backend.read_file("/proc/boot", 1024).decode("utf-8"))

Diagnose and report

Return the source class (mock, recorded or live), tool/target identity, observed state, freshness limits, exact errors and next operator action. Namespace entries and provider declarations do not prove Worker admission, READY or completion. The API and interfaces own schemas.