# session_stop — Stop (and Optionally Delete) OpenCode Sessions

**Script name:** `session_stop`

**Script location:** [`scripts/session_stop.ts`](../../../scripts/session_stop.ts)

**Invoke:**
```bash
# By session ID:
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_stop.ts \
  --session-id ID [--no-delete] [--server URL]

# By tag pattern (stops all matching sessions):
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_stop.ts \
  --tag-pattern PATTERN [--no-delete] [--server URL]
```

**CRITICAL:** Always invoke the script using bash and the format noted above. **Never** try to use the skill as a task, or invoke it through any other method than by directly calling bash with a command of the form listed above under "Invoke:".

## Synopsis

```
session_stop.ts (--session-id ID | --tag-pattern PATTERN) [OPTIONS]
```

Identifies target sessions either by exact session ID or by tag-prefix
matching (the same prefix rule as `session_find_by_prefix`), then terminates
each one. By default sessions are stopped **and** deleted immediately via
`DELETE /session/{id}`. Pass `--no-delete` to record stop-only intent, though
note that the current API performs removal as part of the same operation.

## Arguments

### Target (at least one required)

| Flag | Type | Description |
|------|------|-------------|
| `--session-id ID` | string | Stop this specific session by ID |
| `--tag-pattern PATTERN` | string | Stop all sessions whose tag starts with PATTERN |

If both are provided, `--session-id` takes precedence.

### Optional

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--no-delete` | flag | false | Record stop-only intent; currently removal still occurs |
| `--server URL` | string | `http://localhost:4096` | OpenCode Server base URL |
| `-h`, `--help` | — | — | Print usage to stderr and exit 0 |

## Output

Written to **stdout** as a JSON object:

```json
{
  "stopped": [
    {
      "session_id": "ses_abc123",
      "title": "[AUTO-IMP-001] implementor-worker",
      "action": "stop_and_deleted",
      "success": true,
      "message": "Session ses_abc123 stopped and deleted"
    }
  ],
  "errors": []
}
```

`action` is one of:
- `stop_and_deleted` — stopped and removed (default)
- `stopped` — stop-only intent was requested via `--no-delete`
- `skipped` — an error prevented the operation

## Diagnostics / stderr

```
Looking up sessions with tag prefix "AUTO-IMP"…
Stopping 3 session(s)…
  ✓ ses_abc123 — [AUTO-IMP-001] implementor-worker
  ✓ ses_def456 — [AUTO-IMP-002] implementor-worker
  ✓ ses_ghi789 — [AUTO-IMP-SUP] implementor-supervisor
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | All sessions stopped successfully |
| 1 | One or more sessions failed to stop |

## When to Use This Script

- **Shut down a pool:** use `--tag-pattern AUTO-IMP` to stop the supervisor
  and all workers at once.
- **Restart a specific session:** stop it with `--session-id`, then call
  `session_start.ts` with `--restart` to launch a fresh one.
- **Emergency shutdown:** stop all AUTO-* sessions with `--tag-pattern AUTO-`.

## Usage Examples

```bash
# Stop a specific session
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_stop.ts \
  --session-id ses_abc123

# Stop all sessions in the implementation pool
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_stop.ts \
  --tag-pattern "AUTO-IMP"

# Stop all AUTO-* sessions (entire autonomous system)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_stop.ts \
  --tag-pattern "AUTO-"
```

## Dependencies

- Node.js ≥ 18 (native `fetch` API)
- `npx tsx` for TypeScript execution
- Zero external npm packages
