# session_delete — Delete an OpenCode Session Directly by ID

**Script name:** `session_delete`

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

**Invoke:**
```bash
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_delete.ts \
  --session-id ID [--force] [--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_delete.ts --session-id ID [--force] [--server URL]
```

Deletes a single session directly via `DELETE /session/{id}`. By default
refuses to delete a `busy` (actively processing) session — pass `--force` to
skip this check.

Use `session_stop.ts` instead when you need to stop and remove sessions by
tag pattern, or when you want to stop multiple sessions at once.

## Arguments

### Required

| Flag | Type | Description |
|------|------|-------------|
| `--session-id ID` | string | Session ID to delete (e.g. `ses_abc123`) |

### Optional

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--force` | flag | false | Delete even if the session is currently busy |
| `--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
{
  "session_id": "ses_abc123",
  "title": "[AUTO-IMP-001] implementor-worker",
  "deleted": true,
  "message": "Session ses_abc123 deleted successfully"
}
```

On refusal (busy session, no `--force`):
```json
{
  "session_id": "ses_abc123",
  "title": "[AUTO-IMP-001] implementor-worker",
  "deleted": false,
  "message": "Session ses_abc123 is currently busy. Use --force to delete it anyway."
}
```

## Diagnostics / stderr

```
Checking session ses_abc123…
Deleting session ses_abc123…
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Session deleted successfully |
| 1 | Deletion refused (busy without `--force`), not found, or API error |

## When to Use This Script

Use `session_delete` for immediate removal of a known session ID when:
- The session is idle and you want to clean it up.
- You need to delete a session regardless of state (`--force`).
- You are implementing a cleanup routine that operates on specific IDs.

Use `session_stop.ts` instead if you need to match sessions by tag pattern.

## Usage Examples

```bash
# Delete an idle session
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_delete.ts \
  --session-id ses_abc123

# Force-delete a busy session
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_delete.ts \
  --session-id ses_abc123 \
  --force

# Delete all sessions matching a tag (use session_stop instead for this pattern)
# npx --yes tsx session_stop.ts --tag-pattern "AUTO-IMP"
```

## Dependencies

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