gjc-sdk-session

name	gjc-sdk-session
description	Operate GJC SDK sessions from the CLI (`gjc sdk session list|inspect|send|status|tail|raw` plus the explicit raw control|query|global hatch). Advisory reference: broker-bound, credential-free output; mutating verbs run only when explicitly invoked.

GJC SDK session CLI (advisory)

Advisory reference for interacting with live GJC SDK sessions through the broker-bound gjc sdk session command family. This skill is informational: it never prints endpoint credentials or changes configuration, and it never references removed command routes. Mutating commands are only documented and run when the operator explicitly invokes them.

Broker authority

list, inspect, send, status, and tail resolve sessions through the SDK broker. The broker validates the indexed session against its durable endpoint record and hands the CLI a connection credential the CLI uses and never prints. --agent-dir selects the broker state directory.

Semantic verbs

• gjc sdk session list — broker session.list projected to the versioned, credential-free row DTO (session id, locator, pid, liveness, tombstone, activity, heartbeat, identity provenance, ambiguity).

• gjc sdk session inspect <sessionId> — one indexed row; when the broker is absent, falls back to a credential-free offline projection from the local endpoint discovery record.

• gjc sdk session send <sessionId> --text <prompt> — ordered turn.prompt carrying a caller-chosen operation reference (ULID). --wait polls turn.result with kind: "prompt" until terminal or the wait window elapses; it never cancels a running turn.

• gjc sdk session status <sessionId> <opRef> — lossless turn.result with kind: "prompt" for a previously submitted operation reference.

• gjc sdk session tail <sessionId> — retained transcript replay from the durable checkpoint followed by live event-ring frames. --strict fails closed on retention gaps, --until-idle exits at a terminal turn state, --all-events widens the emitted event kinds, and --cursor resumes from a saved checkpoint token that is re-minted per connection.

Raw hatch

gjc sdk session raw control|query|global dispatches one SDK operation with --op (control/global) or --query (query) plus a JSON input source. Lifecycle globals require --idempotency-key; destructive control operations accept --confirm. Endpoint-disclosure operations are refused by default and stay refused by this skill.

Lossless prompt results

turn.result with kind: "prompt" reports accepted, in_flight, terminal_ok, or failed; only retained-record eviction yields unknown, which means uncertainty, never proof of non-execution. turn.prompt_status remains a legacy prompt-only alias. Never reuse an operation reference as a retry mechanism.

Checkpoint gaps

tail reports a retention_gap with the missing sequence range and a resync checkpoint when retained history or the event ring dropped entries; --strict turns any gap into exit code 1.