gjc-sdk-session

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, tail, and close 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 from the broker. It never reads endpoint discovery records directly: a missing or unavailable broker fails closed rather than exposing endpoint authority outside SDK core.

• 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 close <sessionId> — closes the current live host generation through the broker without attaching. The default idempotency key includes the endpoint generation and incarnation, so retries for one host replay while a resumed host with the same session id gets a new lifecycle identity.

• 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.

Scoped search

gjc sdk search [--scope repo|pwd|global] [--json] lists broker-visible sessions inside one exact scope (default repo: the identical canonical Git worktree, never a path prefix). Every result carries a scope/status envelope (requested and resolved scope, populated, empty, not-in-git-worktree, or unavailable); empty and non-Git results exit 0 and never fall back to a wider scope. Rows are probed after scoping (reachable, unreachable, stale) without printing endpoint credentials.

Local-only spawn

gjc sdk spawn --cwd <dir> --prompt <task> [--model <selector>] [--profile <name>] creates one task-seeded background child through the broker and is legal only inside a live interactive gjc --master session. Each invocation uses a fresh idempotency identity: one identity yields at most one child and one seed prompt, replays return stored outcomes, and a semantically new task requires a new invocation. spawn_in_progress and terminal_uncertain are honest states, never retry triggers. The task and master capability never persist in broker state, logs, or output; spawn is prohibited on MCP, ACP, daemon CLI/raw, Telegram, Discord, and Slack surfaces. Clean up children through the standard session.close path; orphaned children are reaped after sdk.masterOrphanGraceMs.