# Gjc Sdk Session

> GJC SDK session CLI (advisory)

- Skill: `yeachan-heo/gjc-sdk-session` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yeachan-heo/gjc-sdk-session`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yeachan-heo/gjc-sdk-session/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yeachan-heo (https://skillmd.com/u/yeachan-heo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yeachan-heo/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`, 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 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 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`.