singularity doctor

Run the runtime's read-only connectivity and capability preflight. It starts no autonomous cycle and writes no being state.

Invocation

singularity doctor \
  --agent-id <id> \
  --role <role> \
  --environment <environment> \
  --host <host> \
  --workload-id <id> \
  --workload-public-key <64-lowercase-hex> \
  --executable-digest <64-lowercase-hex> \
  --code-digest <64-lowercase-hex> \
  --policy-digest <64-lowercase-hex> \
  --policy-sequence <integer> \
  --las-release-manifest <absolute-file> \
  --las-release-manifest-signature <absolute-file> \
  --las-release-trust-store <absolute-file> \
  --las-release-watermark <absolute-path>

Required inputs

The command requires these options, or their named environment-variable equivalents:

• --agent-id (SINGULARITY_AGENT_ID), --role (SINGULARITY_ROLE), --environment (SINGULARITY_ENVIRONMENT), --host (SINGULARITY_HOST), and --workload-id (SINGULARITY_WORKLOAD_ID). Each is a 1–128 byte immutable identifier using only ASCII letters, digits, -, _, ., or :.
• --workload-public-key, --executable-digest, --code-digest, and --policy-digest. Each value is exactly 64 lowercase hexadecimal characters.
• --policy-sequence <integer>.
• --las-release-manifest, --las-release-manifest-signature, and --las-release-trust-store. Each must name an absolute regular file. --las-release-watermark must be absolute.
• Brama signing material: either --brama-secret-file <owner-only-file> / BRAMA_HMAC_SECRET_FILE, or WISENT_APP_AGENT_AUTH_SECRET when no file is supplied.

Runtime options

• Persona: --agent-name MyAgent, --agent-ticker AGENT, --agent-type general, and --specialty general.
• State and loop: --stimulus <text>, --starting-balance 10, --instance-price 0, --cycle-interval-secs 5, --max-tool-rounds 8, --state-dir .singularity, --workspace ., and --resume.
• Brama: --brama-url http://127.0.0.1:8081, --brama-model any, --max-tokens 2048, --temperature 0.2, --input-price 0, and --output-price 0.
• Las: --las-command node, --las-entrypoint ../las/src/mcp.mjs, --las-only <csv>, --las-skip <csv>, and --required-surfaces skarbiec,finance.
• Most and deadlines: --most-url http://127.0.0.1:8080, optional --most-token-file <owner-only-file>, --http-timeout-secs 120, --mcp-timeout-secs 120, and --shutdown-grace-secs 10.

Every flag above also has the environment-variable spelling exposed by singularity <command> --help.

Checks, output, and state effect

The command checks Brama GET /health, reads GET /v1/models, and requires the configured exact model to be present. The selectors any, any-vision-capable, and task:* do not require an exact catalogue match. When --most-token-file is supplied, it checks that Most has at least one send-capable backend. It then spawns Las and requires at least one <surface>__ tool for every name in --required-surfaces.

Success prints pretty JSON shaped as {"ok":true,"brama_model":...,"most":...,"las_tools":...}. most is null when no token file is configured. The being state directory and activity journal are untouched; Las is stopped before return.

Doctor-specific refusals

• An exact configured model absent from Brama is refused as configuration: configured Brama model is unavailable: <model>.
• A configured Most service with an empty or none backend report is refused as most: Most has no send-capable backend.
• A missing required Las surface is refused as mcp: required Las surface unavailable: <surface>.
• Las refusing startup, MCP initialization, tool listing, or shutdown is an upstream failure and exits 3.

Configuration refusals

Before contacting a surface or writing being state, the runtime refuses with the exact relevant message when:

• stimulus exceeds 65536 bytes or contains NUL: configuration: stimulus must be at most 65536 bytes and contain no NUL;
• the workspace cannot be resolved or is not a directory: configuration: workspace: <error> or configuration: workspace must be a directory;
• --max-tool-rounds is zero: configuration: max tool rounds must be positive;
• a starting balance or price is negative: configuration: prices and balance cannot be negative;
• temperature is not finite or is outside 0 through 2: configuration: temperature must be finite and between zero and two;
• the Las entrypoint is not a file: configuration: LAS entrypoint not found: <path>;
• a release manifest, signature, or trust-store path is not absolute or not a regular file: configuration: <label> must be an absolute regular file;
• the watermark path is relative: configuration: LAS release watermark must be an absolute path;
• an immutable identity component is invalid: configuration: <label> is not a valid immutable identifier;
• a public key or digest is malformed: configuration: <label> must be 64 lowercase hexadecimal characters;
• neither Brama secret source exists: secret file: BRAMA_HMAC_SECRET_FILE or WISENT_APP_AGENT_AUTH_SECRET is required;
• a secret path is not a regular file, is group/world accessible, or is empty: secret file: not a regular file: <path>, secret file: <path> must not be group/world accessible, or secret file: <path> is empty.

Clap refuses a missing required option before runtime code executes. Configuration and secret refusals exit 2; upstream Brama, Las/MCP, or Most failures exit 3; state or I/O failures exit 4; tool, runtime, or JSON failures exit 5.