# semaphore package

## Metadata

| Field | Value |
|---|---|
| Institute | Molodetz Institute — Research & Retrieval Division |
| Subject | background-work-limits |
| Document type | Source Dossier |
| Tier | 1 |
| Source title | semaphore package |
| Source URL | https://pkg.go.dev/golang.org/x/sync/semaphore |
| Source publisher / author | Go project (golang.org/x/sync) |
| Source type | vendor docs |
| Source date (published) | Unknown — not stated (living documentation page) |
| Date researched | 2026-10-18 |
| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
| Research method | both |
| Confidence | High |
| Status | Active |

## Summary

The Go semaphore reference gives tai both halves of the fan-out decision: cap parallel workers with a counting semaphore, and choose explicitly between blocking acquire (backpressure) and TryAcquire (reject-loud). tai takes the reject side: a full pool refuses new spawns with a loud error instead of stalling the caller.

## Key findings

- "Example_workerPool demonstrates how to use a semaphore to limit the number of goroutines working on parallel tasks."
- "This use of a semaphore mimics a typical 'worker pool' pattern, but without the need to explicitly shut down idle workers when the work is done."
- "TryAcquire acquires the semaphore with a non-negative weight of n without blocking. On success, returns true. On failure, returns false and leaves the semaphore unchanged."

## Pros / strengths

- Names the exact fork in the road (block versus refuse) with reference semantics for both, so tai's choice is deliberate rather than accidental.
- Worker-pool-via-semaphore matches tai's shape (threads come and go; only the live count is bounded).

## Cons / limitations / caveats

- Go-side primitive with contexts and goroutines; tai reimplements the policy (count live under a lock, refuse past the cap), not the mechanism.
- No guidance on sizing the cap; tai's number comes from its own arithmetic (scheduler burst plus interactive forks plus verifier headroom).

## Relevance to tai

Direct backing for `AGENTS_MAX_PARALLEL` with reject-loud semantics: `spawn_agent` raises past the cap instead of queueing, because a queued fork would stall the spawning turn's step budget (and blocking waits between workers are a documented deadlock shape). Callers translate the refusal into their own loud message.

## Changelog

| Date | Change |
|---|---|
| 2026-10-18 | Initial dossier created. |