# session_find_by_prefix — Find OpenCode Sessions by Tag Prefix

**Script name:** `session_find_by_prefix`

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

**Invoke:**
```bash
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_find_by_prefix.ts \
  --prefix PREFIX [--exclude-supervisor] [--status busy|idle|all] [--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_find_by_prefix.ts --prefix PREFIX [--exclude-supervisor] [--status busy|idle|all] [--server URL]
```

Lists all sessions and filters to those whose tag starts with the given prefix.
For example, `--prefix AUTO-IMP` matches `AUTO-IMP-001`, `AUTO-IMP-SUP`,
`AUTO-IMP-ISSUE-42`, but **not** `AUTO-IMPL` or `AUTO` alone.

Results are sorted by `last_active` descending (most recently active first).

## Arguments

| Flag | Type | Description |
|------|------|-------------|
| `--prefix PREFIX` | string | Tag prefix to match (no brackets, e.g. `AUTO-IMP`) |
| `--exclude-supervisor` | flag | Exclude sessions whose tag ends with `-SUP` |
| `--status STATUS` | string | Filter by session status: `busy`, `idle`, or `all` (default: `all` — no status filtering) |
| `--server URL` | string | OpenCode Server base URL (default: `http://localhost:4096`) |
| `-h`, `--help` | — | Print usage to stderr and exit 0 |

## Output

Written to **stdout** as a JSON array of `SessionWithStatus` objects sorted by
`last_active` descending:

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Session ID |
| `title` | string | Full session title |
| `tag` | string \| null | Extracted tag |
| `status` | string | `busy` or `idle` |
| `last_active` | number | Epoch ms of last session update |

An **empty array** `[]` means no sessions match the given prefix.

## Diagnostics / stderr

```
Searching for sessions with tag prefix "AUTO-IMP" (excluding -SUP sessions, busy only)…
Found 4/10 session(s) matching prefix "AUTO-IMP".
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success — JSON array written to stdout (may be `[]`) |
| 1 | Fatal error |

## When to Use This Script

- **Find all sessions in a pool:** `--prefix AUTO-IMP` returns all sessions
  belonging to the implementation pool (supervisor + workers).
- **Find only workers, not supervisor:** add `--exclude-supervisor` to remove
  sessions whose tag ends in `-SUP`.
- **Find only busy sessions:** add `--status busy` to restrict results to
  sessions that are currently running.
- **Find only idle sessions:** add `--status idle` to find sessions that have
  finished or are waiting.
- **Audit an entire pool's status:** check whether any workers are stuck or
  have finished.

## Usage Examples

```bash
# Find all implementation pool sessions
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_find_by_prefix.ts \
  --prefix "AUTO-IMP"

# Find all workers (exclude supervisor)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_find_by_prefix.ts \
  --prefix "AUTO-IMP" \
  --exclude-supervisor

# Count busy workers (using --status instead of jq filtering)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_find_by_prefix.ts \
  --prefix "AUTO-IMP" \
  --exclude-supervisor \
  --status busy \
  | jq 'length'

# Find idle sessions in the pool (finished or waiting)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_find_by_prefix.ts \
  --prefix "AUTO-IMP" \
  --status idle

# Find all AUTO-* sessions (the entire autonomous system)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_find_by_prefix.ts \
  --prefix "AUTO-"
```

## Dependencies

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