The queue measures the machine and each owned process group, learns conservative CPU and memory envelopes for recurring jobs, and can delay a job when its predicted demand does not fit current headroom. The operator controls the maximum number of concurrent jobs. Fixed scheduling remains the default, Learn only produces shadow decisions, and Adaptive explicitly enables resource-based admission. Changing mode never terminates an active job.
- A workload family consists of the shared Git repository identity, logical command and repository-relative package or target. Linked worktree paths, branch names and commit hashes do not define the family. Unrelated repositories with the same basename stay separate. Separate clones are not automatically merged by remote URL.
- Variants include meaningful arguments, resource-affecting worker flags, bounded script/configuration and dependency fingerprints, toolchain metadata, source revision and environment provenance. Related variants borrow conservative family evidence instead of losing all learning after a source change. Unknown argument semantics are preserved.
- Optional AGENT_HEAVY_PROFILE names deliberately relate opaque or non-Git workloads. Their contents are hashed and never displayed by the resource API. Cache context is recorded separately; duration predictions remain conservative across observed contexts.
These identities are statistical grouping keys, not reproducible-build or whole-source content hashes. A bounded scan does not read every source file or dependency tree. The controller recomputes neither source nor command content while a job runs. Existing queued jobs without identities migrate from their private acknowledged payloads before admission; unidentified active jobs block new adaptive overlap conservatively.
The resource controller is a separate process (agent-heavy scheduler) that the menu bar app starts and supervises, always restarting it when it exits. The Go queue daemon, also supervised by the app, owns jobs independently of the caller. Native Darwin counters provide host CPU intervals, available memory, pressure, swap rates and disk space. Each job's verified process group is sampled for simultaneous physical footprint and observed cumulative CPU and I/O counters. PID birth identities and repeated membership checks prevent attributing a reused process group to an older job. No new privileged service or Python runtime dependency is needed.
CPU-seconds describe total observed computation, while CPU core demand and peak memory inform overlap. Summing simultaneous worker footprints avoids adding unrelated lifetime peaks. Workers born and exited entirely between samples, or peaks entirely between samples, remain invisible; observed totals are lower bounds. Completeness means the required sampled intervals were available, not kernel-enforced lifetime accounting. A sample is complete when it read every process that lasted through it, so workers starting or exiting mid-sample are normal work rather than missing evidence. Native CPU counters are converted from Mach ticks to nanoseconds, because Apple Silicon reports about 41.67 ns per tick and Intel reports 1 ns.
Execution start time is published with the ownership lease. A controller that first observes a job late, lacks its execution start, misses a sampling interval, or crosses sleep/clock discontinuities marks its learning history incomplete. A sample that fails for any other reason counts only if the controller samples the job again, since the final sample of nearly every job races the job's own exit. A failed sample never advances the last observation, so an earlier gap still fails finalization's check against the worker's end. Once the queue reports a job finished, samples only track what still holds its capacity and add nothing to its evidence. Finalization checks the last observation against the worker's recorded execution end, including jobs that finish during an outage, and preserves actual execution duration. Healthy current intervals can recover admission readiness without turning the earlier unobserved work into complete training evidence.
Private SQLite history retains bounded numeric run records and opaque workload identities. Predictions prefer the exact variant, then related family evidence, then a conservative prior. Exact variants need five comparable successful observations within 30 days before lowering the cold-start or family envelope. Family transfers use an extra margin. Underestimates and peaks from failed or incomplete runs raise retained upper evidence without refreshing successful evidence. Old evidence gradually loses confidence. A collector restart, observation gap, cancellation or nonzero exit cannot establish that a job is cheap, and old observation timestamps are preserved across restarts.
Shadow and adaptive admission decisions are also retained in bounded private SQLite audit history, including numeric predictions and fixed explanation text. Unchanged decisions are coalesced without rewriting their original timestamp. These records support later comparison with measured outcomes without retaining command contents.
The controller adjusts learned resource envelopes within fixed operator constraints. It does not autonomously raise concurrency limits, reduce emergency reserves, change test-worker counts, or alter commands. Pair-specific interference models, phase forecasts, energy prices and monetary billing are outside this version; measured resource envelopes determine overlap.
Adaptive submissions are durable held tasks in the Go queue. The controller checks current queue state, fresh host observations, memory pressure, swap rate, disk headroom, the operator ceiling and current owned work. A candidate reserves its predicted memory peak; an active job reserves potential growth above its current footprint. Current host usage is counted once. CPU reservations similarly account for observed activity and future demand.
Automatic starts require an expiring grant tied to the job token, boot and scheduling generation. Immediately before executing a command, the helper verifies the grant and current resource status under the existing private ownership lease lock, rechecking freshness after blocking reads. This check also enforces the latest parallel ceiling. Pending starts reserve capacity until their lease is acquired or the grant expires. Newly acquired but unsampled leases block further starts. Pressure, stale observations and controller failures revoke or invalidate pending automatic admission. Manual Start now records an explicit override. Predicted CPU demand must fit above background usage even when the queue is otherwise empty; an estimate exceeding the CPU budget needs fewer workers or an explicit operator override.
Unfamiliar jobs run alone until comparable successful evidence accumulates. Resource-fitting backfill can use spare capacity behind a temporarily blocked job of equal priority, but higher-priority jobs retain precedence. An older waiting job reserves the next opportunity after a bounded wait, preventing starvation. An estimate exceeding the machine's budget produces an actionable explanation instead of an unexplained delay.
Missing or stale resource telemetry holds new adaptive starts. The UI preserves monitoring failure separately from queue connectivity, and Fixed and Learn only remain selectable. Returning to Fixed returns managed jobs to fixed scheduling and preserves an intentionally paused queue. Existing force-start, cancellation, legacy-owner exclusion and daemon crash ownership rules remain in force. Suspending a process would not reclaim its memory, so adaptive admission does not use suspension as recovery.
The app ships the resource modules and a separate bundled resource-controller helper without replacing or restarting a running queue daemon. Local development can run the controller against a deliberately isolated queue with agent-heavy scheduler; in production the app starts it independently of the daemon. Do not point test controllers at the operator's real queue.
Focused tests cover worktree identity and variants, sampled counter resets and process churn, censored learning, conservative estimates, bounded private storage, budget arithmetic, stale grants, generation changes, pressure recovery, concurrent lease observations, fairness, controller restart and mode transitions. Real-daemon acceptance uses private Go daemon instances and simulated resource demand to exercise stashed admission, overlapping known jobs, lowering the ceiling, manual override, controller loss, queued-job migration and ordinary fixed scheduling. Native, browser, schema, API and installer regressions cover the visible controls and packaging. macOS CI runs on Intel and Apple Silicon.