# session_wait_till_supervisor_idle — Block Until a Supervisor Slot Opens

**Script name:** `session_wait_till_supervisor_idle`

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

**Invoke:**
```bash
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_wait_till_supervisor_idle.ts \
  --expected-supervisors N --timeout SECONDS [--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_wait_till_supervisor_idle.ts \
  --expected-supervisors N --timeout SECONDS [--server URL]
```

Blocks until the number of busy supervisor sessions drops below the expected
supervisor count, or until the timeout is reached.

A supervisor session is any session whose extracted tag ends with `-SUP`
(e.g., `[AUTO-IMP-SUP]`, `[AUTO-PRMRG-SUP]`).  All supervisor sessions across
the entire system are counted — there is no prefix filtering.

This is a convenience wrapper around
[`session_wait_till_idle`](../session_wait_till_idle/) with `--mode supervisors`.

## Arguments

| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--expected-supervisors N` | integer | yes | Positive integer; the number of supervisors expected to be running. Blocks while `busy_supervisor_count >= N`. |
| `--timeout SECONDS` | integer | yes | Positive integer; maximum seconds to block. |
| `--server URL` | string | no | OpenCode Server base URL (default: `http://localhost:4096`) |
| `-h`, `--help` | — | — | Print usage to stderr and exit 0 |

## Matching Rules

A session is counted as a **busy supervisor** when:
1. Its status is `busy`
2. Its extracted tag (from `[TAG] title`) ends with `-SUP`

All supervisor sessions across the system are counted. There is no prefix
filter — the `-SUP` suffix is the universal convention for supervisors.

## Output

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

| Field | Type | Description |
|-------|------|-------------|
| `waited` | boolean | `true` if the script had to block at least once |
| `timed_out` | boolean | `true` if the timeout was reached before the condition was met |
| `elapsed_seconds` | number | Wall-clock seconds spent waiting (1 decimal precision) |
| `busy_count` | number | Final busy supervisor count at the moment the script returned |
| `max_pool_size` | number | The expected supervisor count that was used as threshold |
| `mode` | string | Always `"supervisors"` |
| `tag_prefix` | null | Always `null` (supervisors do not use a prefix filter) |

Example:
```json
{
  "waited": true,
  "timed_out": false,
  "elapsed_seconds": 10.1,
  "busy_count": 1,
  "max_pool_size": 2,
  "mode": "supervisors",
  "tag_prefix": null
}
```

## Diagnostics / stderr

```
Waiting for supervisor pool to have fewer than 2 busy session(s) — timeout: 120s
[0.0s] Busy supervisor sessions (tag ends with -SUP): 2 / max 2
[5.1s] Busy supervisor sessions (tag ends with -SUP): 1 / max 2
Condition met after 5.1s — 1 busy supervisor(s) < expected 2
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Always — check the `timed_out` field in JSON output to distinguish condition-met from timeout |
| 1 | Fatal error (missing args, invalid values, API unreachable after retries) |

## When to Use This Script

- **Waiting for a supervisor to finish:** an orchestrator that manages multiple
  supervisors can use this to gate launches — ensuring no more than N
  supervisors are running concurrently.
- **Replacement launches:** before restarting a crashed supervisor, wait for the
  existing count to drop to confirm the old one actually stopped.

## Usage Examples

```bash
# Wait for fewer than 2 supervisors to be busy, 120s timeout
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_wait_till_supervisor_idle.ts \
  --expected-supervisors 2 --timeout 120

# Quick check: is any supervisor slot available? (1s timeout)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_wait_till_supervisor_idle.ts \
  --expected-supervisors 2 --timeout 1
```

## Dependencies

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