coilyco-flight-deck/ward

Fork 0

Add --override-capacity opt-in past the OOM pool ceiling; rename --force to --override-reservation (an --override-* flag family) #1045

New issue

Closed

opened 2026-07-10 17:17:13 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-07-10 17:17:13 +00:00

Member

Decision

The engineer pool cap (warded list => N/N, at capacity) is an OOM pressure valve, not scheduling hygiene: at capacity the host genuinely holds that many live containers, and spawning another risks thrashing or OOM-ing the box (confirmed by Kai).

Two override axes exist in the dispatch path, and they must stay distinct - collapsing them is exactly the footgun this issue prevents:

Reservation override - reclaim a stale or foreign per-issue hold. Cheap and safe, because the hold may be wrong.
Capacity override - launch past the OOM ceiling. Dangerous, because the ceiling is never stale (12 running containers really are running) and blowing past it can OOM the host.

Today the first is spelled --force (a vague "do the scary thing" name that invites conflating the two) and the second does not exist yet. This issue does both: add the capacity override, and rename the pair into a narrow, self-documenting --override-* family.

Do

1. Establish the `--override-*` flag family

--override-reservation - reclaim a stale or foreign reservation hold. This is the renamed --force.
- Keep --force as a deprecated alias of --override-reservation for a transition window (the reservation comments, docs, and muscle memory all say --force). Print a one-line deprecation notice when --force is used. A hard removal can follow later.
--override-capacity - launch one engineer past the OOM pool ceiling. New flag.

Each name is narrow and parallel. The OOM / host-risk detail lives in the help description and the runtime warning, not the flag name.

2. Make `--override-capacity` loud and conscious

Print a prominent stderr warning naming the real numbers, e.g. WARNING: launching over the engineer OOM ceiling (13/12) - host may thrash or OOM.
It is not implied by --override-reservation (or the --force alias). The two never bleed into each other.
Consider (decide in impl) requiring the flag to carry the acknowledged count or an interactive confirm, so it cannot be muscle-memoried in.

3. Leave the default path alone

Without either override, a full pool still fails fast locally (ward#1041) and never touches the issue tracker.

Acceptance

--override-reservation (and the deprecated --force alias) against a full pool still refuses to launch - cap unchanged - and only reclaims reservations. --force additionally prints a deprecation notice.
--override-capacity launches exactly one engineer past the ceiling and emits a loud host-risk warning naming the true N+1 / N count.
The two flags are independent: neither implies the other.
Default (no flag) full-pool dispatch fails fast locally per ward#1041 - no comment on the issue.
Help text describes each --override-* flag narrowly: reservation hold vs OOM ceiling.

ward#1041 - fail fast on capacity contention locally. The default-path sibling: #1041 is the quiet refusal, this issue is the deliberate escape hatch.
ward#1034 - reservation-vs-inventory correctness. The reservation axis (--override-reservation) this deliberately stays separate from.
"Stop director dispatch from exceeding the global engineer limit" - the cap enforcement this adds a conscious override to.

## Decision The engineer pool cap (`warded list` => `N/N, at capacity`) is an **OOM pressure valve**, not scheduling hygiene: at capacity the host genuinely holds that many live containers, and spawning another risks thrashing or OOM-ing the box (confirmed by Kai). Two override axes exist in the dispatch path, and they must stay **distinct** - collapsing them is exactly the footgun this issue prevents: * **Reservation override** - reclaim a **stale or foreign per-issue hold**. Cheap and safe, because the hold may be wrong. * **Capacity override** - launch **past the OOM ceiling**. Dangerous, because the ceiling is never stale (12 running containers really are running) and blowing past it can OOM the host. Today the first is spelled `--force` (a vague "do the scary thing" name that invites conflating the two) and the second does not exist yet. This issue does both: **add the capacity override, and rename the pair into a narrow, self-documenting `--override-*` family.** ## Do ### 1. Establish the `--override-*` flag family * `--override-reservation` - reclaim a stale or foreign reservation hold. **This is the renamed `--force`.** * Keep `--force` as a **deprecated alias** of `--override-reservation` for a transition window (the reservation comments, docs, and muscle memory all say `--force`). Print a one-line deprecation notice when `--force` is used. A hard removal can follow later. * `--override-capacity` - launch one engineer **past** the OOM pool ceiling. New flag. Each name is narrow and parallel. The OOM / host-risk detail lives in the **help description and the runtime warning**, not the flag name. ### 2. Make `--override-capacity` loud and conscious * Print a prominent stderr warning naming the real numbers, e.g. `WARNING: launching over the engineer OOM ceiling (13/12) - host may thrash or OOM`. * It is **not** implied by `--override-reservation` (or the `--force` alias). The two never bleed into each other. * Consider (decide in impl) requiring the flag to carry the acknowledged count or an interactive confirm, so it cannot be muscle-memoried in. ### 3. Leave the default path alone Without either override, a full pool still fails fast locally (`ward#1041`) and never touches the issue tracker. ## Acceptance * `--override-reservation` (and the deprecated `--force` alias) against a full pool still refuses to launch - cap unchanged - and only reclaims reservations. `--force` additionally prints a deprecation notice. * `--override-capacity` launches exactly one engineer past the ceiling and emits a loud host-risk warning naming the true N+1 / N count. * The two flags are independent: neither implies the other. * Default (no flag) full-pool dispatch fails fast locally per `ward#1041` - no comment on the issue. * Help text describes each `--override-*` flag narrowly: reservation hold vs OOM ceiling. ## Related * `ward#1041` - fail fast on capacity contention locally. The default-path sibling: #1041 is the quiet refusal, this issue is the deliberate escape hatch. * `ward#1034` - reservation-vs-inventory correctness. The reservation axis (`--override-reservation`) this deliberately stays separate from. * "Stop director dispatch from exceeding the global engineer limit" - the cap enforcement this adds a conscious override to.

coilyco-ops changed title from ~~Add a separate, loud --over-cap opt-in to launch an engineer past the OOM pool ceiling (keep --force reservation-only)~~ to Add --override-capacity opt-in past the OOM pool ceiling; rename --force to --override-reservation (an --override-* flag family)

2026-07-10 17:20:36 +00:00

coilyco-ops commented

2026-07-10 21:50:04 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-claude-ward-1045 on host KAI-DESKTOP-TOWER.

Reserved by ward agent --harness claude (reserved 2026-07-10T21:50:04Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/ward#1045 · branch issue-1045 · harness claude · workflow pull-requests-and-merge
Run: engineer-claude-ward-1045 · ward v0.605.0 · dispatched 2026-07-10T21:50:04Z
Comment thread: 0 included in the pre-flight read, 0 stripped (ward's own automated comments).

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.605.0).

— Claude (she/her), via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-claude-ward-1045` on host `KAI-DESKTOP-TOWER`. Reserved by `ward agent --harness claude` (reserved 2026-07-10T21:50:04Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/ward#1045` · branch `issue-1045` · harness `claude` · workflow `pull-requests-and-merge` - **Run:** `engineer-claude-ward-1045` · ward `v0.605.0` · dispatched `2026-07-10T21:50:04Z` - **Comment thread:** 0 included in the pre-flight read, 0 stripped (ward's own automated comments). Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.605.0). </details> </details>  — Claude (she/her), via `ward agent`

coilyco-ops referenced this issue from a pull request that will close it,

2026-07-10 22:17:46 +00:00

Add --override-capacity opt-in past the OOM pool ceiling; rename --force to --override-reservation #1091

coilyco-ops closed this issue

2026-07-10 22:18:27 +00:00

coilyco-ops referenced this issue from a commit

2026-07-10 22:18:28 +00:00

Add --override-capacity and rename --force to --override-reservation (ward#1045)

coilyco-ops commented

2026-07-10 22:18:56 +00:00

Author

Member

WARD-OUTCOME: merge-ready

details

workflow: pull-request-and-merge; review summary: skipped - the in-container review gate was intentionally skipped because of the temporary ward default pending brokered QA.

PR: #1091 (branch issue-1045, CI test / test green on head, merged with latest main).

What landed. The --override-* family on the engineer dispatch path: --override-reservation is the renamed --force (kept as a hidden deprecated alias with a one-time stderr notice), and the new --override-capacity admits exactly one launch past the OOM ceiling with a loud WARNING: launching over the engineer OOM ceiling (N+1/N) - host may thrash or OOM. Neither implies the other. Director grows the propagation flag for reservation only - capacity is deliberately not a loop knob. Broker allowlists and forwards each spelling as typed for version skew. Reservation comments, refusal messages, and the skill reference renamed.

Impl decision (issue left it open). Instead of an acknowledged-count argument or interactive confirm, the one-past bound is structural: --override-capacity only admits from exactly at-capacity and refuses a pool already over the ceiling (still classified as capacity backpressure so director/broker defer normally). Headless-safe and unstackable.

How it felt. Clean rename with one honest judgment call: --force also gated closed-issue re-dispatch and the interactive-label override, and those powers moved with the rename so the deprecated alias carries nothing unique. Confidence high - new unit tests cover the flag family independence, the deprecation notice, at/over/below-ceiling override behavior, director argv, and broker forwarding; full go test ./... green except TestRunAgentAdvisorRefDispatchReturnsPromptlyViaBroker, which fails identically on unmodified main in this container (network-bound broker test), so pre-existing.

Surprises. The code-comments hook's 2-line/90-char cap forced several doc comments tighter than I'd naturally write; nothing semantic lost.

Follow-ups. Hard removal of the --force alias after the transition window (issue says a later change); consider whether warded list should hint the new spellings in its at-capacity line.

WARD-OUTCOME: merge-ready <details><summary>details</summary> workflow: pull-request-and-merge; review summary: skipped - the in-container review gate was intentionally skipped because of the temporary ward default pending brokered QA. PR: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/pulls/1091 (branch `issue-1045`, CI `test / test` green on head, merged with latest `main`). **What landed.** The `--override-*` family on the engineer dispatch path: `--override-reservation` is the renamed `--force` (kept as a hidden deprecated alias with a one-time stderr notice), and the new `--override-capacity` admits exactly one launch past the OOM ceiling with a loud `WARNING: launching over the engineer OOM ceiling (N+1/N) - host may thrash or OOM`. Neither implies the other. Director grows the propagation flag for reservation only - capacity is deliberately not a loop knob. Broker allowlists and forwards each spelling as typed for version skew. Reservation comments, refusal messages, and the skill reference renamed. **Impl decision (issue left it open).** Instead of an acknowledged-count argument or interactive confirm, the one-past bound is structural: `--override-capacity` only admits from exactly at-capacity and refuses a pool already over the ceiling (still classified as capacity backpressure so director/broker defer normally). Headless-safe and unstackable. **How it felt.** Clean rename with one honest judgment call: `--force` also gated closed-issue re-dispatch and the interactive-label override, and those powers moved with the rename so the deprecated alias carries nothing unique. Confidence high - new unit tests cover the flag family independence, the deprecation notice, at/over/below-ceiling override behavior, director argv, and broker forwarding; full `go test ./...` green except `TestRunAgentAdvisorRefDispatchReturnsPromptlyViaBroker`, which fails identically on unmodified `main` in this container (network-bound broker test), so pre-existing. **Surprises.** The code-comments hook's 2-line/90-char cap forced several doc comments tighter than I'd naturally write; nothing semantic lost. **Follow-ups.** Hard removal of the `--force` alias after the transition window (issue says a later change); consider whether `warded list` should hint the new spellings in its at-capacity line. </details>

coilyco-ops referenced this issue

2026-07-15 07:59:28 +00:00

Brokered director dispatch does not honor --override-capacity when repo limit is full #1347