# session_find_by_tag — Find OpenCode Sessions by Exact Tag

**Script name:** `session_find_by_tag`

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

**Invoke:**
```bash
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_find_by_tag.ts \
  --tag TAG [--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_tag.ts --tag TAG [--server URL]
```

Lists all sessions and filters to those whose title starts with exactly `[TAG]`.
The match is case-sensitive and exact — `AUTO-IMP-SUP` matches only sessions
whose title begins with `[AUTO-IMP-SUP]`, not `[AUTO-IMP]` or `[AUTO-IMP-SUP-EXTRA]`.

## Arguments

| Flag | Type | Description |
|------|------|-------------|
| `--tag TAG` | string | Exact tag string to match, without brackets (e.g. `AUTO-IMP-SUP`) |
| `--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 (same schema as `session_list`):

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Session ID |
| `title` | string | Full session title |
| `tag` | string \| null | Extracted tag (will equal the requested `--tag` for all results) |
| `status` | string | `busy` or `idle` |
| `last_active` | number | Epoch ms of last session update |

An **empty array** `[]` means no session with that exact tag was found.

## Diagnostics / stderr

```
Searching for sessions with exact tag [AUTO-IMP-SUP]…
Found 1/8 session(s) with tag [AUTO-IMP-SUP].
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success — JSON array written to stdout (may be `[]`) |
| 1 | Fatal error (missing required arg or API failure) |

## When to Use This Script

Use `session_find_by_tag` when you need to check for one specific session by
its exact tag — for example, checking whether a specific supervisor or worker
is currently running.

## Usage Examples

```bash
# Find the implementor pool supervisor
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_find_by_tag.ts \
  --tag "AUTO-IMP-SUP"

# Check if a specific issue worker is running
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_find_by_tag.ts \
  --tag "AUTO-IMP-ISSUE-42"

# Get the session ID (if found)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_find_by_tag.ts \
  --tag "AUTO-IMP-SUP" \
  | jq -r '.[0].id // "not found"'
```

## Dependencies

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