Cohesix root shell and cohsh — user guide

Choose your interface

Use the root shell to bring up a Queen, check its hardware and network, and recover when a host connection is unavailable. Use cohsh on your Mac or Linux host to inspect the Queen, retain logs, submit authorised work, upload telemetry and run repeatable checks.

Setting up a Queen? Start with Bring up and check the Queen, then Connect cohsh and Test the connection. Already connected? Go to Do useful work.

This guide describes the current source interfaces, not a promise that an older release implements every option. Keep the target image, host binaries and selected generated configuration together. Check the running image’s help and the installed binary’s --help. Historical fixture credentials are not valid deployment credentials; see release migration.

Find what you need

Know which prompt you are using

Commands below omit the prompt so they can be copied. Each procedure says where to enter them. Bash examples run on the host, from the installation or repository root. Shell variables such as COH_BIN are conveniences for these examples; they do not expand inside cohsh or .coh files. Set COH_BIN and the relevant connection variables again in each new host terminal.

Neither Cohesix console is a POSIX shell. There is no cd, sudo, package manager, shell pipeline, command substitution or general-purpose program launcher at cohesix> or coh>. Namespace paths are absolute. The host’s out/operator/queen-log.txt and the Queen’s /log/queen.log are different files on different machines.

Bring up and check the Queen

1. Prepare the target and capture serial

Start with an image built and staged for the actual target. Image construction, SD-card flashing, readback and boot identity are covered by Hardware bring-up. Do not reflash a working installation merely to change its network settings.

For a Pi, connect the serial adapter described by that hardware setup and identify its actual host device. Only one terminal or capture program may own that device. On the Mac host, this example captures a new boot:

RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)"
SERIAL_DEVICE="/dev/cu.usbserial-0001"  # Replace with your verified device.
EVIDENCE_DIR="$PWD/out/pi4-proof/$RUN_ID"
umask 077
mkdir -p "$EVIDENCE_DIR"
minicom -D "$SERIAL_DEVICE" -b 115200 -o \
  -C "$EVIDENCE_DIR/pi4-serial.log"

Use 115200 baud, 8 data bits, no parity, one stop bit and no flow control. Start capture before powering on when retaining boot evidence. Do not open another serial client while minicom is running. Logs and packet captures can contain sensitive deployment information; review them before sharing.

For an already running QEMU Queen, use the serial console in its launcher terminal. Host TCP normally connects to the launcher’s forwarded address and port, rather than the guest’s internal address. The separate cohsh --transport qemu mode is a diagnostic boot/log transport, not the normal live shell.

2. Choose the Pi’s network settings

The staged Pi image stops at the Cohesix boot menu. Its first option says whether saved settings or the selected manifest’s defaults are active.

For first setup, choose Change network settings, then Automatic (DHCP) or Manual (static IPv4) and Ethernet (wired) or Wi-Fi (wireless). Manual setup collects the address, subnet prefix length and optional gateway. Review the result, then choose Boot once without saving for a temporary check or Save settings and restart to retain it. After restart, select the boot option with the saved settings.

The default image uses USB keyboard input for the boot menu. A visible menu on serial does not mean serial keystrokes are its selected input. Wi-Fi name and password entry requires the local USB keyboard and HDMI display; the bootloader deliberately refuses serial-only password entry. Do not type a PSK into minicom, a captured command or shell history. When local input is unavailable, follow the private cohesix.env editing procedure in First-boot network policy.

Network choices do not provision console tokens or ticket signing keys. Those must match the selected image’s deployment configuration. Do not reset saved settings as a first response to an authentication error.

3. Check the root console

Wait for cohesix>. On the target serial console, enter these commands one at a time, waiting for each response to finish before sending the next:

help
ping
bi
caps
mem
smp
netstats

Record the actual address and port reported for this boot. The examples below use 192.168.10.50:31337; change them to match your Queen. In Wi-Fi mode, profile_backend=bcmgenet-v5 with active_driver=cyw43 is not by itself a mismatch: one describes the profile and the other the selected physical path.

netstats is diagnostic, not a non-interfering performance sampler. The Pi direct-GENET implementation can perform a bounded causal owner refresh. Do not mix repeated diagnostic commands into a timed benchmark.

While an authenticated TCP response owns the output stream, a competing physical help, netstats or namespace read may return reason=busy detail=network-response-pending. Wait for that response to finish before retrying the refused read. A physical ping remains available: its PONG, terminal and prompt complete independently of the TCP stream’s END. Neither surface’s response may leave the other, or queued HDMI output, permanently waiting for progress it prevents.

A serial prompt does not prove the local USB/HDMI seat is ready. The Pi HDMI prompt is withheld until keyboard command admission and display readiness are established. For a local-seat check, type a real command on the USB keyboard and confirm its echo and response. Use usb status from serial to inspect the result; startup history alone is not current input proof.

4. Escalate only the relevant diagnostic

These are profile-gated commands. usb enable-kbd and usb probe-kbd are active operations, not passive inspection. Legacy wifi retry, wifi load-fw and wifi probe-ht return an ownership refusal on the linked runtime; they are not recovery procedures. Use the reported blocker and Failure modes, rather than repeatedly issuing them.

Connect cohsh

Select the matching host binary

From an extracted Mac or Linux host bundle root:

./scripts/setup_environment.sh --check
export COH_BIN="$PWD/bin"
"$COH_BIN/cohsh" --help

For a new installation, run ./scripts/setup_environment.sh first as described in Quickstart; it can install host dependencies. A Pi image bundle alone does not provide your Mac’s host executables.

From an already built source checkout root, use this instead:

export COH_BIN="$PWD/out/cohesix/host-tools"
"$COH_BIN/cohsh" --help

Source developers can substitute cargo run -p cohsh -- for "$COH_BIN/cohsh". That builds the current Cargo feature selection; it does not make an old target match a new host binary. Use the selected generated policy, and remain in the installation root so relative configuration and local file paths resolve correctly.

Direct TCP: one shell owns the connection

Use this when operating the Queen with one host process. Quit a direct SwarmUI, bridge, mount or other shell first. Do not leave a gateway connected while starting a competing direct client. Serial remains an independent operator surface and can stay open.

Obtain the console credential provisioned for this image. In host Bash, select its existing private file and the address verified above:

export COH_AUTH_TOKEN_REF="file:$HOME/.config/cohesix/queen-console.token"
export COH_TARGET_HOST="192.168.10.50"
export COH_TARGET_PORT="31337"
unset COHSH_TCP_HOST COHSH_TCP_PORT

"$COH_BIN/cohsh" --transport tcp \
  --tcp-host "$COH_TARGET_HOST" --tcp-port "$COH_TARGET_PORT" \
  --role queen

The credential file must already contain the deployment token; setting its path does not create or discover a token. Restrict access to the file. An env:NAME reference is also supported. Do not substitute a published fixture, bootstrap or changeme.

For a local QEMU instance, set COH_TARGET_HOST=127.0.0.1 and use its forwarded port. The explicit unset avoids inherited COHSH_TCP_* overrides; see Credential and environment precedence.

A successful start reports an attached Queen session and displays coh>. Interactive auto-attachment also attempts a bounded Queen log tail. The prompt alone is not proof of attachment: a failed connection can leave a detached shell. Run ping to confirm.

Without --role, the shell starts detached. At coh>, use attach queen. To change attachment, use detach, then attach <role> [ticket]. detach closes the current transport session but keeps the shell open; quit exits. Worker attachments require a valid role-matching ticket with a subject.

REST: use the gateway that already owns TCP

For simultaneous shell, UI and automation work, start one hive-gateway using Host tools: connect and verify. Select its Pi or QEMU runtime profile correctly. The gateway, not cohsh, owns the Queen’s TCP connection.

In another host terminal, set COH_BIN again and connect:

export COH_REST_URL="http://127.0.0.1:8080"
"$COH_BIN/cohsh" --transport rest --rest-url "$COH_REST_URL" --role queen

Read operations inherit the gateway’s upstream scope. REST writes additionally need both the gateway request-authentication token and a delegated caller ticket. Load their values privately before starting a write-capable shell:

: "${COH_REST_AUTH_TOKEN:?load the gateway request-authentication token}"
: "${COH_REST_TICKET:?load a valid delegated caller ticket}"
export COH_REST_AUTH_TOKEN COH_REST_TICKET
"$COH_BIN/cohsh" --transport rest --rest-url "$COH_REST_URL" --role queen

The ticket needs an unexpired lifetime, subject and write scope covering the actual destination. Permission to write /log does not permit a production intent at /queen/intents/ctl. The gateway verifies the caller ticket and intersects it with its upstream authority; --role queen does not grant unrestricted access. The current REST attachment selector accepts only Queen.

Keep gateway HTTP on loopback or behind an approved authenticated tunnel/TLS boundary. Neither this console transport nor the gateway supplies TLS itself. On a Jetson, 127.0.0.1 refers to that Jetson, not your Mac.

Test the connection

Start with a small read-only check

At coh>, run:

ping
ls /
ls /proc
cat /proc/lifecycle/state
cat /proc/authority
tail /log/queen.log 16

Confirm that every operation completes, the namespace is readable under the intended role, and the lifecycle and authority fields match your deployment. Read the returned state; an OK CAT acknowledgement does not mean the value was ONLINE. A policy refusal is different from an unavailable transport.

If an optional path is absent, inspect the selected profile and source version rather than treating it as an empty value. Do not continue into mutation tests until attachment, lifecycle and policy are understood.

Run and finish the network self-test

Use direct TCP cohsh for the authenticated network exercise. At coh>:

nettest

Record the positive run_generation from OK NETTEST detail=started run_generation=.... That line means started, not passed. Keep the same connection open, allow the bounded 15-second test window to finish, exercise it with ping, then read netstats:

ping
netstats

Require a terminal verdict for that same run generation, with running=false. pass and peer-assisted-pass identify different supported test paths; read their component fields. running, none, a failed verdict or a different run is not a pass. With an isolated console-network child, peer-assisted success depends on post-admission response drain, TX and later RX/TCP progress for the matching authenticated connection. Its UDP echo field can truthfully be false. ICMP reachability is a separate check.

Do not translate this wait into WAIT 15000 in a .coh file: its local wait limit is 2000 ms. A serial-only nettest admission cannot substitute for the required authenticated peer interaction.

Run the installed self-tests deliberately

First inspect what this image publishes at coh>:

ls /proc/tests
cat /proc/tests/selftest_negative.coh
cat /proc/tests/selftest_quick.coh

Then run the reduced-mutation quick check:

test --mode quick --no-mutate

--no-mutate is not a universal read-only sandbox. It skips spawn, kill and Worker telemetry tails in the installed scripts, plus their associated assertions. It still runs negative tests, including attempted writes that are expected to be refused. Review installed scripts before using this mode on a working deployment. Use the earlier explicit read-only commands when even attempted writes are inappropriate.

For an authorised test environment, examples are test --mode full --timeout 120 and test --mode smp --no-mutate. The default timeout is 30 seconds; accepted values are 1–120 seconds. A timeout is a failed check, not a reason to raise every retry setting.

Human output reports selftest PASS or selftest FAIL and the first failed check. --json emits a single-line report object with ok, mode, elapsed_ms, checks and schema version. Other shell output can surround that JSON line; do not treat the whole stdout stream as one JSON document. Automation must require ok=true and a successful script exit.

Internal scripts may close their session. cohsh attempts to restore the previous attachment afterwards, preserving outer script response bookkeeping; a failed restoration is reported. Verify attachment before continuing work.

These are operational checks, not release acceptance. A QEMU result does not qualify a physical Pi, and mock success qualifies neither. For milestone or release claims use the staged, provenance-bound Test plan.

Do useful work

Inspect state and save logs

At coh>, browse before assuming a path or object exists:

ls /queen
ls /shard
cat /proc/lifecycle/state
cat /proc/authority
log
tail /log/queen.log 16
cat /log/queen.log

log is a convenience for the newest 64 retained Queen log records. tail <path> [lines] returns a finite snapshot, not tail -f; explicit counts are 1–256. Reissue a bounded tail when needed. cat /log/queen.log also includes the retained trusted boot-audit reserve in sequence order. Neither operation promises logs that have already been evicted.

To save the retained log, create a directory in host Bash before starting the shell:

mkdir -p out/operator

Then, at coh>:

log dump out/operator/queen-log.txt

This creates a local .txt file, containing log payload rather than wire OK/END framing. The parent directory must exist, and an existing destination is refused. Use a new filename for each capture. log dump out/operator/queen-log.txt --force explicitly replaces an existing capture. A failed or incomplete target read is not a complete log export.

Append an operator note

This intentionally changes the Queen log. Use a Queen attachment with the necessary write authority; through REST, also supply a ticket scoped to /log. At coh>:

echo operator-check: serial-and-host-readback-complete > /log/queen.log
tail /log/queen.log 4

Confirm the note is present in returned data. The > is cohsh command syntax, not host redirection, and the operation appends rather than truncates. One outer pair of quotes may surround the text, but this is not shell quoting: there is no variable expansion, and a literal > inside the payload is not supported by this parser. Newline, carriage return and NUL payloads are refused.

The equivalent serial-console write is path-first:

echo /log/queen.log operator-check: serial-note

It remains subject to the physical console’s role and write policy. Do not paste the cohsh spelling into serial or the serial spelling into cohsh.

Upload a telemetry file

Use this to retain a bounded host observation under a device identifier, not to copy arbitrary files into a general-purpose target filesystem. In host Bash, create a small example file (explicitly labelled as an operator observation):

mkdir -p out/operator
printf '%s\n' '{"source":"operator","event":"connectivity-check-complete"}' \
  > out/operator/queen-check.ndjson

At coh>, using authorised telemetry write access:

telemetry push out/operator/queen-check.ndjson --device operator-check
ls /queen/telemetry/operator-check/seg

The acknowledgement reports seg_id, record count, encoded bytes, original source bytes and mode=inline|reference. Read the segment named in that acknowledgement. For example, only when the returned ID is seg-000001:

cat /queen/telemetry/operator-check/seg/seg-000001

The source must be non-empty. Supported extensions are .txt and .log (text/plain), .json (application/json), .ndjson (application/x-ndjson) and .csv (text/csv). Local paths in these commands must not contain whitespace; cohsh is not a general shell argument parser.

Small, bounded UTF-8 content uses inline cohsh-telemetry-push/v1 records. Binary input or content exceeding the inline envelope budget uses coh-ref-c/v1 chunk references. Reference mode uploads offsets, lengths and hashes, not the referenced file bytes. Retain the unchanged source file under your content-retention policy. The generated limits also cap reference size, entry count and per-device retention; repeated uploads can evict older segments.

Submit and observe Worker requests

A Worker request manages a declared Cohesix control-plane task. It does not install Linux, launch an arbitrary application or execute CUDA inside the Queen. GPU discovery, actual GPU programs and PEFT tooling remain host-side; follow Host tools for those workflows.

First inspect /proc/authority and /proc/lifecycle/state. The convenience commands below write compatibility /queen/ctl. They do not automatically construct a strict intent. Production profiles that disable the compatibility path require the next procedure instead.

In a compatibility-enabled test deployment, at coh>:

spawn heartbeat ticks=100 ttl_s=120 ops=500
ls /shard

Read the returned control outcome and discover the published Worker through its shard directory. Do not assume the next Worker has a particular ID. For a concrete illustration, when the selected eight-bit shard layout publishes worker-1, its canonical shard is 13:

ls /shard/13/worker
cat /shard/13/worker/worker-1/telemetry

Substitute the actual published label and ID in your session. The canonical shape is /shard/<label>/worker/<id>/telemetry. /worker/<id>/telemetry is only a compatibility alias when the selected manifest enables it.

An accepted control append is admission, not READY. Inspect the structured Worker observation and keep these axes separate:

Once the specific test Worker has been identified, kill worker-1 submits its termination request in a compatibility deployment. Replace that ID; never kill a guessed Worker. Observe its subsequent state or removal. Termination admission is not proof that teardown has finished.

Other accepted convenience forms are:

spawn gpu gpu_id=GPU-0 mem_mb=4096 streams=2 ttl_s=120 priority=1 budget_ttl_s=180 budget_ops=500
spawn lora

GPU-0 is illustrative: use a GPU identifier actually published for the selected deployment and a resource request its policy permits. These commands are not evidence that a GPU exists or that training has run.

Unknown or duplicate keys are rejected. spawn bus and spawn worker-bus return a model-only refusal without a control write. Role availability and capacity remain generated-profile decisions.

ls /shard is a bounded view of up to 64 active shard labels, not a complete large-fleet index. Complete discovery enumerates the generated shard address space and reads each shard’s Worker directory, as SwarmUI and the benchmark harness do. Empty shards do not imply failed discovery; a failed read or malformed/misplaced Worker record does.

Submit a production Queen intent

Use /queen/intents/ctl when strict intents are required. An envelope contains schema, id, idempotency_key, issued_unix_ms, the selected writer_epoch and cmd as a JSON string containing the existing command object. A nested JSON object in cmd is not the same format.

Before proceeding, confirm the selected epoch with cat /proc/authority, confirm that a new heartbeat Worker is appropriate, and obtain write authority for /queen/intents/ctl. This procedure deliberately creates one request. It does not bypass lifecycle, policy approval, ticket or capacity checks.

In host Bash, enter the verified epoch and create a saved command file once. Python supplies the current issue time and new identifiers; exclusive file creation prevents accidentally replacing a request whose outcome is unknown:

mkdir -p out/operator
umask 077
read -r -p 'Writer epoch reported by this Queen: ' COH_WRITER_EPOCH
export COH_WRITER_EPOCH
python3 - <<'PY'
import json
import os
from pathlib import Path
import time
import uuid

raw_epoch = os.environ['COH_WRITER_EPOCH']
if not raw_epoch.isascii() or not raw_epoch.isdecimal():
    raise SystemExit('Writer epoch must be the unsigned integer read from /proc/authority')
epoch = int(raw_epoch)
if not 0 <= epoch <= (1 << 64) - 1:
    raise SystemExit('Writer epoch is outside the unsigned 64-bit range')
intent = {
    'schema': 'queen-intent/v1',
    'id': 'heartbeat-' + uuid.uuid4().hex,
    'idempotency_key': uuid.uuid4().hex,
    'issued_unix_ms': time.time_ns() // 1_000_000,
    'writer_epoch': epoch,
    'cmd': json.dumps({'spawn': 'heartbeat', 'ticks': 100}, separators=(',', ':')),
}
payload = json.dumps(intent, separators=(',', ':'))
if len(payload.encode('utf-8')) > 2048:
    raise SystemExit('Intent exceeds the console echo payload bound')
path = Path('out/operator/spawn-heartbeat.coh')
with path.open('x', encoding='utf-8') as stream:
    stream.write('# Author: Lukas Bower\n')
    stream.write('# Copyright 2026 Lukas Bower\n')
    stream.write('# SPDX-License-Identifier: Apache-2.0\n')
    stream.write('# Purpose: Submit one retained, explicitly identified heartbeat request.\n')
    stream.write('echo ' + payload + ' > /queen/intents/ctl\nEXPECT OK\nquit\n')
print('Created', path, 'with intent id', intent['id'])
PY
"$COH_BIN/cohsh" --check out/operator/spawn-heartbeat.coh

Inspect the saved file locally. Then, with the direct interactive client closed and the correct console credential still selected, execute it from host Bash:

"$COH_BIN/cohsh" --transport tcp \
  --tcp-host "$COH_TARGET_HOST" --tcp-port "$COH_TARGET_PORT" \
  --role queen --script out/operator/spawn-heartbeat.coh

For an existing gateway, use --transport rest --rest-url "$COH_REST_URL" instead of the TCP options, with the request-auth token and appropriately scoped delegated ticket loaded. Do not run both alternatives.

After successful submission, reconnect and inspect /proc/queen/dedupe, the Queen log and the actual Worker observation. The dedupe view is bounded; an entry missing from its recent list is not proof that no effect occurred.

An interrupted write has an unknown outcome, not an automatic failure. Reconcile the retained outcome before retrying. An authorised strict retry must reuse the exact saved request, including both identifiers, issue time, epoch and command bytes. Do not rerun the generator to manufacture a new identity. Exact duplicates return the retained outcome; changed fields under the same identity produce an idempotency conflict. Dedupe capacity is bounded, and its authority lifetime does not survive a VM restart as a durable promise. Do not reboot to clear it and resubmit. Full details are in M27a authority.

The same envelope mechanism can carry an existing kill, bind or mount Queen command object. It is not a universal wrapper for every control file: use each namespace’s own documented payload contract.

Control the Queen lifecycle

These commands change node state and can affect ongoing work. First read the state at coh>:

cat /proc/lifecycle/state

For a Queen currently ONLINE or DEGRADED, an authorised maintenance sequence begins:

lifecycle cordon
cat /proc/lifecycle/state

Only after confirming DRAINING, request lifecycle drain and inspect the state again. Resume only when maintenance and workload policy permit it: lifecycle resume, followed by another state read. Do not paste all transitions blindly into a live fleet.

cohsh writes the lifecycle control namespace, not a shell command on the host. The server remains authoritative for every transition. Use reboot only for an intentional platform restart, with Queen authority and a supported backend, after retaining evidence and considering work in progress.

.coh scripts

A .coh file is a deterministic sequence of cohsh commands and assertions. It has no variables, substitutions, branching, loops, includes, macros or runtime downloads. One command per line; blank lines are ignored. # begins a comment, including inline comments, so do not put a literal # in a payload that must survive script parsing. Use host tooling to prepare concrete files.

Create, check and run a health script

In host Bash:

mkdir -p out/operator
cat > out/operator/health.coh <<'COH'
# Author: Lukas Bower
# Copyright 2026 Lukas Bower
# SPDX-License-Identifier: Apache-2.0
# Purpose: Check attachment and read bounded Queen state without workload writes.
ping
EXPECT OK
ls /proc
EXPECT OK
cat /proc/lifecycle/state
EXPECT OK
cat /proc/authority
EXPECT OK
tail /log/queen.log 16
EXPECT OK
quit
COH
"$COH_BIN/cohsh" --check out/operator/health.coh

--check reads local policy and validates script structure without connecting to a target. It does not prove that a path exists, credentials are valid, commands are authorised or the target will accept a payload.

Close any direct interactive owner, then run the file in host Bash:

"$COH_BIN/cohsh" --transport tcp \
  --tcp-host "$COH_TARGET_HOST" --tcp-port "$COH_TARGET_PORT" \
  --role queen --script out/operator/health.coh

Retain a transcript without losing the command’s failure status:

set -o pipefail
"$COH_BIN/cohsh" --transport tcp \
  --tcp-host "$COH_TARGET_HOST" --tcp-port "$COH_TARGET_PORT" \
  --role queen --script out/operator/health.coh \
  2>&1 | tee out/operator/health-transcript.txt

This pipeline is host Bash, not .coh syntax. Choose a new transcript filename when preserving an earlier run. A script stops on an unexpected command, transport or assertion failure and exits non-zero. Failure details include the source line, last command, response source and bounded history.

Use the right assertion

The recorded response normally prefers a transport acknowledgement over later payload output. Therefore cat /proc/lifecycle/state followed by EXPECT OK checks that the read succeeded; it does not assert state=ONLINE.

To assert returned data, use the read-condition form. For a deployment expected to be online, this is a .coh fragment:

WAIT 2000 TAIL /proc/lifecycle/state SUBSTR state=ONLINE
EXPECT OK

After asynchronous Worker admission, wait on the existing /log/queen.log path for that Worker’s WORKER_TASK_READY record before reading its sharded telemetry path. The Worker path can return invalid-path before construction, and a refusal stops the wait immediately. The condition is checked against completed data, not merely an ACK; the wait never repeats a mutation. Each read retains its own transport response timeout, so 2000 ms is not an override of network timeouts. The synchronous host model emits the same role marker with mode=host-model after creating its Worker namespace; that marker is mock readiness, not target Worker evidence.

A deliberate negative test may place EXPECT ERR immediately after the command whose refusal is expected. Do not use it to hide an unexpected production write failure. Scripts contain at most 256 non-empty statements. Generated scripts, such as boot_v0.coh, must be regenerated rather than edited manually.

Automate a self-test

In a test environment where the installed negative checks are appropriate, create a file whose command is test --mode quick --no-mutate --json and run it with --script and an explicit attached role, just like health.coh. Inspect the report’s ok field as well as process exit status. In interactive mode a printed failure report does not by itself make the eventual shell exit status a failed test run. Prefer --script for automation.

Retain a live trace or rehearse offline

To record the read-only health script against the live target, close another direct owner and run in host Bash:

"$COH_BIN/cohsh" --transport tcp \
  --tcp-host "$COH_TARGET_HOST" --tcp-port "$COH_TARGET_PORT" \
  --role queen --script out/operator/health.coh \
  --record-trace out/operator/health.trace

Live recording supports TCP and REST. Add --trace-target-id, --trace-session-id, --trace-manifest-sha256 and --trace-image-sha256 only with values known for the captured target; unspecified identity remains unknown, not inferred proof. Captures are bounded by generated size and duration limits. Incomplete capture is an error, not a complete trace.

Replay that live capture offline, without reconnecting to the Queen:

"$COH_BIN/cohsh" --replay-trace out/operator/health.trace

For an isolated in-process rehearsal instead:

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

Mock state exists only in that cohsh process. A separate mock tool or a later process does not see its Workers or notes. Legacy fixture replay and mock GPU seeding also depend on compiled features. Neither replay nor mock is fresh hardware evidence. See Operator evidence for capture, inspection, attestation and evidence-pack contracts.

Command reference

Use help for a concise index and man <command> for the complete installed manual, including all arguments, examples, limits, authority and recovery. man ls includes the namespace tree; man spawn explains each Worker role, resource argument and readiness check; man authority gives the production strict-intent procedure. man lists all topics. login resolves to attach.

From the host terminal, cohsh --man spawn works without credentials, configuration or a running Queen. cohsh --man lists topics, and cohsh --man spawn | less uses the host’s pager. At coh>, type man spawn. Unknown topics and extra arguments are errors and send no target request. SwarmUI reads the same manuals; its own help describes its smaller command surface and gates, including its raw-JSON spawn syntax. The physical root console provides concise help; detailed manuals run on the host.

Root console

Run help on the active image for profile availability. These commands are entered at cohesix>, not in host Bash.

Root test directs you to host cohsh; it is not the host self-test runner. Pi-only usb and wifi families are described in the bring-up and advanced sections. Arbitrary-memory hexdump is disabled in production/release policy; a separately enabled debug profile permits only bounded immutable root-code inspection. It is not a normal operator command.

cohsh interactive commands

Enter these at coh> or as command lines in a .coh file. Support of a forwarded diagnostic still depends on the selected transport and target.

Durable CUDA recipe composition is available through the external coh plan/apply/watch/explain/verify/recover commands with --recipe; see Recoverable CUDA recipes. The shared cohsh/SwarmUI manuals explain this host-only boundary. These options do not change root-console or .coh grammar.

mem, cachelog, usb, wifi and hexdump are not dispatched by the current host cohsh command handler. Use the physical root console for them, even though some appear in the compiler-generated shared grammar below. Shared parser vocabulary and host CLI implementation are not identical inventories.

The qemu transport launches staged artifacts and rejects writes; use TCP or REST for actual namespace work. REST is a bounded gateway projection, not an arbitrary raw-console relay. A locally listed diagnostic can be unsupported by that transport; use direct TCP when it is free, or serial, rather than assuming a locally displayed help item guarantees a REST operation.

Input limits

The shared console currently bounds a complete command line to 2304 bytes, an absolute path to 96 bytes, a ticket to 224 bytes and an echo payload to 2048 bytes. Raw console spawn JSON has a separate 192-byte bound; this is not the strict-intent envelope limit. Namespace walks are bounded to eight components, and selected namespace/profile policy can impose smaller limits. Keep payloads on one line and allow for the newline appended by cohsh.

A general msize=8192 transport budget does not enlarge the console’s smaller path, line or payload bounds. Split work using the owning interface’s supported segmentation, not invented continuation syntax.

Response and session rules

Target acknowledgements use OK <VERB> and typed ERR <VERB> details. The acknowledgement is emitted before any payload. Bounded refusal and truncation records use reason=<busy|quota|cut|policy> where applicable; inspect that reason before selecting recovery or retry behavior. Streaming LS, CAT and TAIL responses complete with END. cohsh handles the transport framing and labels acknowledgements [console]; it also prints local status and payload lines. Do not send a plain terminal/netcat session to the framed TCP endpoint and expect serial behaviour.

A refusal normally has no side effect unless its owning interface says otherwise. An absent response is not a refusal. Batches containing writes are not replayable merely because a connection failed part-way through them. Retry/backoff policy never grants authority to duplicate an uncertain mutation.

TCP quit is complete only after exact OK QUIT, client write-half close and peer EOF on that same connection. Missing ACK, extra post-terminal frames, timeout or missing EOF fails script mode; QUIT is not retried on a replacement connection. Do not interpret the host process disappearing as proof of a clean remote close.

CLI options and credentials

Use cohsh --help for compiled options. Most sessions need only transport, endpoint, role and a privately supplied credential.

Ticket minting is an issuer operation requiring the correct signing material; it is not how an ordinary user bypasses missing access. It requires --role and conflicts with an input ticket, script/check and trace modes. Worker subjects are required; delegated write tickets additionally need a subject, scope and bounded lifetime. Follow Authority and Host tools authentication.

Credential and environment precedence

TCP credential references are exactly env:NAME or file:/absolute/path. A selected reference that cannot be read or validated fails without falling back to a different credential. Reads are bounded to 4096 bytes; empty, malformed, placeholder and whitespace/control-containing live token values are refused. File sources are reread on new authentication for rotation.

Pool, retry and heartbeat overrides also have corresponding COHSH_* environment forms (for example COHSH_RETRY_TIMEOUT_MS); explicit flags take precedence for those numeric settings. Do not infer that rule for TCP port, whose implementation behaves differently as shown above.

REST filesystem response windows compose 5000 ms queue admission, the larger of the gateway control/telemetry response bounds, and 5000 ms delivery grace. The canonical 120000/120000 ms gateway profile therefore needs a 130000 ms client envelope. --rest-response-timeout-ms precedes COHSH_REST_RESPONSE_TIMEOUT_MS; the selected window cannot be smaller than the composed gateway envelope. This is not a retry allowance and does not change the separate connection, metadata or body-transfer bounds.

Troubleshooting

Capture the failing command, complete bounded response, target image/profile, boot/connection identity and relevant serial context. Keep credentials out of reports. Preserve the first fault before rebooting or opening another TCP connection that replaces latest-session evidence.

Advanced diagnostic reference

The following expandable sections retain field interpretation for incident and driver analysis. They are not a required reading path for ordinary shell work. Use the matching image’s records; unavailable, stale and unobserved values are not zero-valued proof. Detailed driver contracts are in DRIVERS.md, external schemas in INTERFACES.md, and acceptance requirements in TEST_PLAN.md.

USB_OLDGOOD_RETAINED v=1 task=<u32> token=0x<8hex> link_epoch=<u32> link_token=0x<8hex> epoch=<u32> seq=<u32> mask=0x<8hex> topology=0x<8hex> input_gen=<u32> commit=<u32> source=<linked-runtime-hid|none>
USB_OLDGOOD_CURRENT contracts=usb-local-seat+pcie-root owners=<driver-owned|missing>+<driver-owned|missing> descriptors=<sealed|missing>+<sealed|missing> command_ready=<yes|no> proof_gate=<0|14> blocker=<none|receipt-missing|usb-owner-missing|pcie-owner-missing|usb-descriptor-missing|pcie-descriptor-missing|command-not-ready> root_pointer=no

nettest: generation=<connection> run_generation=<run> enabled=<bool> running=<bool> verdict=<none|running|pass|peer-assisted-pass|fail> tx_ok=<bool|na> udp_echo_ok=<bool|na> tcp_ok=<bool|na> console_ok=<bool|na> peer_assisted_ok=<bool|na>

isolated_progress: pcont=<candidates>/<admitted>/<rejected> peff_us=<n> preason=0x<n>
isolated_units: output_ok=<n>
isolated_state: ycalls=<n> ycredit_us=<n> yinvalid=0x<n>

netstats: genet_direct ...
netstats: genet_direct_flags ...
netstats: genet_direct_before ...
netstats: genet_direct_before_ring ...
netstats: genet_direct_irq ...
netstats: genet_direct_irq_source ...
netstats: genet_direct_notification ...
netstats: genet_direct_dpc ...
netstats: genet_direct_dma ...
netstats: genet_direct_ring ...
netstats: genet_direct_peer ...

netstats: cyw43_publication schema=v1 candidates=<u64> minted=<u64> consumed=<u64> rejected=<u64> reasons=0x<hex>
netstats: cyw43_publication_cut schema=v1 probe=<u64> entry=<u64> pre_network=<u64> revoked=<u64>
netstats: cyw43_productive_window schema=v1 opened=<u64> idle_admitted=<u64> closed=<u64> ready_rechecks=<u64>
netstats: genet_compact schema=v1 stage=<u64> deferred=<u64> fault=<u64> unsupported=<u64> dispatch=<u64> stage_turns=<u64> rotations=<u64>
netstats: genet_compose schema=v1 composed=<u64> no_pending=<u64> not_sealed=<u64> backpressure=<u64> identity_drift=<u64>
netstats: genet_defer schema=v1 passive=<u64> command=<u64> compose_open=<u64> compose_backpressure=<u64> fence=<u64> prior_batch=<u64> control_busy=<u64> output_missing=<u64> stage_backpressure=<u64>
netstats: isolated_seam schema=v2 name=<command-created-root-observe|command-created-publish|command-publish-root-observe|dispatch-stage|stage-control-observe|stage-output-drained|output-drained-root-observe> n=<u64> bad=<u64> ms=<total>/<last>/<max> h=<hex>/<hex>/<hex>/<hex>/<hex> hs=<0|1> [pairs=<u64>]

[smp:registry/v1] base=0 count=2 registration=present,missing generation0=1/1/1 generation1=none terminal=yes,unknown

netstats: mcs_quantum schema=v1 hz=<u64> samples=<u64> material=<u64> periods=<u64> invalid=<u64> invalid_period=<u64>
netstats: mcs_quantum_lane schema=v1 wifi=<u64> genet=<u64>
netstats: mcs_quantum_total schema=v1 period_us=<u64> run_us=<u64>
netstats: mcs_quantum_timing schema=v1 period_avg_us=<u64> period_max_us=<u64> run_avg_us=<u64> run_max_us=<u64>
netstats: mcs_quantum_period schema=v1 bounds_us=1000,3000,6000,9000,12000,20000 buckets=<u64>,<u64>,<u64>,<u64>,<u64>,<u64>,<u64>
netstats: mcs_quantum_run schema=v1 bounds_us=1000,3000,6000,9000,12000,20000 buckets=<u64>,<u64>,<u64>,<u64>,<u64>,<u64>,<u64>
netstats: mcs_quantum_last schema=v1 lane=<wifi|genet> generation=<u64> conn=<u64> progress=0x<hex> pending=0x<hex>->0x<hex> period_us=<u64> run_us=<u64> exit=<YIELD|RETAIN|FENCE|FAULT>
netstats: mcs_quantum_exit schema=v2 yields=<u64> retains=<u64> fences=<u64> faults=<u64> pending=<u64> stalled=<u64>
netstats: mcs_command_dispatch schema=v1 samples=<u64> invalid=<u64> avg_ms=<u64> last_ms=<u64> max_ms=<u64>
netstats: mcs_observe_dispatch schema=v1 samples=<u64> invalid=<u64> avg_ms=<u64> last_ms=<u64> max_ms=<u64>
netstats: mcs_yield schema=v1 hz=<u64> samples=<u64> invalid=<u64> pending=<u64> wifi=<u64> genet=<u64>
netstats: mcs_yield_timing schema=v1 total_us=<u64> avg_us=<u64> max_us=<u64>
netstats: mcs_yield_hist schema=v1 bounds_us=1000,3000,6000,9000,12000,20000 buckets=<u64>,<u64>,<u64>,<u64>,<u64>,<u64>,<u64>
netstats: mcs_yield_cause schema=v2 reserve=<u64> no_successor=<u64> passive=<u64> recovery=<u64> operator=<u64> other=<u64>
netstats: mcs_yield_last schema=v1 lane=<wifi|genet> generation=<u64> conn=<u64> pending=0x<hex> trigger=<RESERVE_GUARD|NO_PRODUCTIVE_SUCCESSOR|PASSIVE_ADMISSION|RECOVERY_FENCE|OPERATOR_ROTATION|OTHER_BOUNDARY> hiatus_us=<u64>
netstats: mcs_budget_guard schema=v2 totals=<u64>,<u64>,<u64>,<u64> pending=<u64>,<u64>,<u64>,<u64>
netstats: mcs_budget_reason schema=v1 cap=<u64> clock=<u64> reserve=<u64> policy=<u64> mask=0x<hex>

The host-only cohesix-journey identity|validate|doctor|run command installs with the Python tools and composes the existing CUDA/LoRA lifecycle. See Adoption and CI workflows for configuration, scoped approval, retry identity and verified outcome exit codes. It introduces no VM console verb.

Graphical operation

SwarmUI connects to a Queen or Hive Gateway through an editable connection dialog. Namespace actions, validated control forms, installed host operations, canonical evidence and offline replay do not require console grammar. The optional expert console retains man, role and key=value spawn compatibility, and transport-supported root diagnostics. Review and confirmation do not replace target admission, and an ACK does not imply execution. The host operation schema is shared with coh; credentials stay out of profiles and previews.

Compiler-generated reference

These marker-delimited blocks are retained mirrors of the standalone coh-rtc snippets. They describe the generated configuration, not proof that your currently running target has that configuration. Do not edit their contents by hand; update manifest/IR inputs and regenerate affected outputs. In particular, the shared grammar is not the complete host dispatcher and its path-first echo is not interactive cohsh syntax.

Implementation and related references

When changing the CLI, update the owning parser/transport, affected tests and this guide together. Keep examples explicit about their prompt, transport, authority, side effects and success condition. Regenerate the marker blocks instead of editing them. Documentation examples are procedures, not records that a particular Queen or release has passed them.