---
name: oysterun-session-ops
description: Use for repo-local Oysterun Host session operations from this project, including starting or opening sessions, restarting or resuming where supported, sending chat messages, creating current-session loop messages, sending terminal commands, and reading recent live session messages through Host HTTP APIs without relying on global Codex skills or global oysterun-session-control helpers.
metadata:
  short-description: Repo-local Oysterun session operations
---

# Oysterun Session Ops

Use this skill when Owner/TL asks a worker to operate an Oysterun Host session through project-local tooling. This skill is source-local to this repo and must not depend on global `~/.codex/skills` or global `oysterun-session-control`.

Canonical product skill source lives at `skills/oysterun-session-ops/`. The repo-local Codex mirror at `.codex/skills/oysterun-session-ops/` and the Host packaged asset at `host-service/assets/product-skills/oysterun-session-ops/` are generated mirrors. Run `node tool_scripts/sync_product_skills_to_codex.mjs` after changing this skill and `node tool_scripts/check_product_skill_mirrors.mjs` before review.

## Guardrails

- Do not print tokens, passwords, cookies, auth headers, or raw login responses.
- Fail fast on missing Host origin, auth inputs, session ids, agent ids, folders, or message text.
- Use current repo Host endpoints; do not invent alternate stack/port maps.
- Do not start, restart, or stop Host unless the route explicitly asks for Host lifecycle work.
- Do not use browser/MCP unless the route explicitly asks for browser verification.
- Treat upload routes as forbidden; `/session/uploads` is deprecated and returns `410`.

## Prereqs

Set the Host origin and either a bearer token or dashboard credentials:

```bash
export OYSTERUN_HOST_ORIGIN="http://127.0.0.1:2322"
export OYSTERUN_DASHBOARD_TOKEN="..."          # preferred when already issued
```

or:

```bash
export OYSTERUN_HOST_ORIGIN="http://127.0.0.1:2322"
export OYSTERUN_DASHBOARD_USERNAME="admin"
export OYSTERUN_DASHBOARD_PASSWORD="..."
```

The helper obtains a token from `/auth/login` only when `OYSTERUN_DASHBOARD_TOKEN` is absent. It never prints the token.

## Helper

Use the bundled helper for deterministic local operations. In repo-local Codex tasks, the mirrored helper path is:

```bash
node .codex/skills/oysterun-session-ops/scripts/session_ops.mjs <command> [args]
```

When Host injects this skill into a live session, the helper path is:

```bash
node .claude/skills/oysterun-session-ops/scripts/session_ops.mjs <command> [args]
```

The helper exits non-zero on missing required env/input or non-2xx Host responses and redacts secret-shaped fields in output.

## Common Operations

Health check:

```bash
node .codex/skills/oysterun-session-ops/scripts/session_ops.mjs health
```

Start a fresh session:

```bash
node .codex/skills/oysterun-session-ops/scripts/session_ops.mjs start \
  --agent-id routec-worker \
  --agent-folder /absolute/path/to/agent/folder \
  --session-name routec-worker-session
```

Open means identify the active session and, when needed, report the web route rather than driving a browser:

```bash
node .codex/skills/oysterun-session-ops/scripts/session_ops.mjs status \
  --session-id <host_session_id>
```

Session web route shape:

```text
/app/sessions/<host_session_id>/chat
```

Restart a live session where Host supports it:

```bash
node .codex/skills/oysterun-session-ops/scripts/session_ops.mjs restart \
  --session-id <host_session_id>
```

Same-session resume where supported requires a stopped source session and matching `session_id` / `source_session_id`:

```bash
node .codex/skills/oysterun-session-ops/scripts/session_ops.mjs resume \
  --session-id <stopped_host_session_id> \
  --agent-id routec-worker \
  --agent-folder /absolute/path/to/agent/folder
```

Branch resume creates a new Host session from a persisted source transcript:

```bash
node .codex/skills/oysterun-session-ops/scripts/session_ops.mjs branch-resume \
  --source-session-id <source_host_session_id> \
  --agent-id routec-worker \
  --agent-folder /absolute/path/to/agent/folder
```

Send a chat message:

```bash
node .codex/skills/oysterun-session-ops/scripts/session_ops.mjs send \
  --session-id <host_session_id> \
  --text "Owner message"
```

Create or enable a current-session loop using the dedicated loop CRUD endpoint:

```bash
node .codex/skills/oysterun-session-ops/scripts/session_ops.mjs create-loop \
  --session-id <host_session_id> \
  --interval 15m \
  --text "run .codex/prompts/loop_cmd.md"
```

Send a loop command/message through normal chat parsing when a route explicitly asks for the chat-command path:

```bash
node .codex/skills/oysterun-session-ops/scripts/session_ops.mjs send \
  --session-id <host_session_id> \
  --text "loop every 15m run .codex/prompts/loop_cmd.md"
```

Send a current-session terminal command:

```bash
node .codex/skills/oysterun-session-ops/scripts/session_ops.mjs terminal-command \
  --session-id <host_session_id> \
  --command "pwd"
```

Read recent live buffered messages:

```bash
node .codex/skills/oysterun-session-ops/scripts/session_ops.mjs recent \
  --session-id <host_session_id> \
  --limit 20
```

## Endpoint Map

- `POST /session/start`: start a runtime-backed Host session.
- `POST /session/restart`: restart a live Host session and preserve `session_id`.
- `POST /session/resume`: same-session resume for a stopped Host session.
- `POST /sessions/resume`: branch/fork resume from stored transcript.
- `POST /session/send`: send normal chat text; Host may classify loop commands from text.
- `POST /session/loops`: create current-session loop schedule.
- `GET /session/history?session_id=<id>`: read live buffered messages.
- `GET /session/status?session_id=<id>`: read live session status.
- `POST /session/terminal-command`: send a shell command to the live session cwd.

## Reporting

When using this skill, report:

- command run, with tokens/passwords omitted
- Host origin
- session id and agent id
- operation result
- retained proof path if the route required evidence
- any failure response with secrets redacted
