Oompa Local Efficiency

Oompa local efficiency

Keep parallel reasoning and routine authorized delivery moving without human prompt churn. Reduce duplicated validation, conflicting local compute, unnecessary checkouts, stale state, and verified disposable disk use while preserving sandbox, provider, repository, and release gates.

Choose the mode

• Install or update this Mac: run bun run scripts/bootstrap.ts --apply from this skill directory, then run it again with --check. This manages Codex automatic approval review and workspace permissions plus Claude Code Auto mode and global guidance; it never enables a bypass-permissions mode.
• Inspect this Mac: run oompa-local-efficiency --json (or bun run scripts/doctor.ts --json) to check the managed global Codex and Claude settings, then run bun run scripts/workspace-audit.ts and bun run scripts/session-audit.ts. All three are read-only. Add --sizes only when the slower recursive worktree-size estimate is useful. The workspace audit reports each Hraness repository's managed guidance status; use repo-adoption.ts --apply --root ABSOLUTE-REPO for each reported needs-update repository.
• Measure local throughput: run oompa-throughput-report for the bounded, privacy-safe scheduler history. Treat repeat command digests and silent tasks as review heuristics, never as proof of waste or abandonment.
• Inspect a browser wait: run oompa-host-queue --lane=browser-auth --json. It reports cooperating wrappers, safe labels, elapsed waits and owner-reported capability stages. Missing, stale and older-wrapper information is unknown; the snapshot never establishes free capacity or FIFO position. Add an explicit --task-id=UUID to oompa-host-run only when sharing that task identity is appropriate. It never reads task identities from the environment.
• Request a cooperative handoff: address the exact observed run with oompa-host-queue --request-handoff=RUN_ID --request-id=REQUEST_ID --label=LABEL --json. Use a fresh safe ASCII request ID for each intent and the identical ID and label when reconciling an uncertain delivery. A recorded receipt acknowledges a notice, not release. The holder finishes and collects its current browser session before returning the lane; do source editing and external waits after that return. Never signal another holder or change its lease to obtain a slot.
• Run heavyweight local work: resolve oompa-host-run to its installed absolute path and use ABSOLUTE-Oompa-HOST-RUN --mode=shared|heavy|exclusive --lane=compute|browser-auth|mac-native --label=LABEL -- COMMAND ... through reviewed host access. Keep the complete wrapper and child argv visible to Codex.
• Run a reviewed interactive child that owns Ctrl-C: opt in with --tty-signal-owner=child only when descriptors 0, 1 and 2 are actual POSIX terminals. Before the exact child starts, SIGINT still cancels admission. While it runs, terminal SIGINT reaches the foreground child directly; the wrapper neither duplicates it nor records cancellation before the child settles. Direct SIGINT sent only to the wrapper is not a supported post-start stop in this mode; use SIGTERM for external cancellation. HUP, QUIT and TERM, existing noninteractive group cleanup, default parent ownership and lease collection remain unchanged. This option grants no interactive/auth authority.
• Record or reuse deterministic focused validation: use oompa-validate. Reuse is opt-in and is never valid for a required final integration, merge-queue, deployment, release, authenticated-browser, or network-sensitive gate.
• Reclaim Git worktrees: audit first with workspace-audit.ts, then invoke worktree-cleanup.ts separately in each owning repository with every approved absolute path named through --remove.
• Adopt or check repository guidance: use repo-adoption.ts --check or --apply. It edits only the exact managed policy block in root AGENTS.md and adds an @AGENTS.md import to root CLAUDE.md while preserving existing Claude-specific guidance. When a repository is already in scope for a change, check and refresh its managed baseline in that same task-owned change and existing final gate, preserving unmanaged rules; do not open a separate rollout solely to repeat expensive checks.
• Audit CI ref isolation: use oompa-ci-ref-audit --root ABSOLUTE-REPO. Review every candidate; fix only workflows whose complete-history gate can import unrelated refs, and preserve the complete-history scan itself.

Run scripts from the installed skill directory when the convenience commands are unavailable. bootstrap.ts installs or refreshes those commands under the user's Bun bin directory. It verifies a minimal pinned Slopcamera host-resource runtime in a source-commit-specific directory under the user's local data directory; it never replaces a global Slopcamera package or command. Runtime upgrades keep the existing HRA state root, profile IDs and inherited lease protocol. Do not move or rewrite a live scheduler ledger to match a runtime's product name.

This plugin was previously named hra-local-efficiency. bootstrap.ts --apply migrates that installation in place: it replaces exactly one well-formed hra-local-efficiency managed block in each managed file with the current block, moves the Codex rule file and the two profile files to their current names while keeping their unmanaged content, retargets the hra-* command links, and installs hra-* compatibility links beside the oompa-* commands. --check reports every legacy remnant as drift, requires the compatibility links only on a machine that already has a legacy command name, and refuses a file that carries both legacy and current markers. repo-adoption.ts migrates a repository's legacy AGENTS.md and CLAUDE.md blocks the same way.

Preserve the invariants

• Treat a user request that places a repository and outcome in scope as standing authorization for routine task-owned commits, pushes, pull requests, merges, releases, and deployments after the gates applicable to that action pass. Build confidence through relevant automated checks, bounded diagnostics, and independent review, not a second conversational confirmation. Passing checks does not expand task scope or authority.
• Separate artifact admission from live qualification and operational activation. Applicable automated source, security, package/install, and provenance evidence can admit an artifact without live provider qualification; live proof is not a universal publication prerequisite. Preserve explicit live acceptance criteria and require relevant live evidence for claims that depend on it. If publication or an artifact's install, upgrade, or default-use path activates risky unqualified behavior, keep that behavior guarded or disabled, or obtain bounded relevant evidence before shipping or activation. Preserve the identity, target, capacity, migration, and recovery guards applicable to the operational effect.
• For eligible public packages, use verified immutable GitHub Release artifacts as canonical distribution independently of optional exact-byte npm mirrors. Prefer OIDC where provider policy permits; retain required staged approvals and private-package access boundaries.
• Replace an obsolete gate through a reviewed source and policy change with corresponding tests, never an ad hoc skip. Runtime-enforced approvals, access controls, branch and environment protections, and safety policies remain binding. Ask for user input only for a material product decision, missing credentials or authority, unavoidable interactive authentication, an out-of-scope destructive action, or a failure that cannot be handled safely and autonomously.
• Prefer short-lived repository workload identities, npm trusted publishing, and scoped GitHub App tokens over personal sessions and reusable secrets. Use unattended stable publication and production promotion where provider and repository policies permit. Establish machine authority once and verify it with a non-publishing preflight where available. Retain account 2FA and provider-required approval bound to the exact staged artifact; never remove a package policy declaration or change its coordinate to evade that control. Batch unavoidable authentication at the final boundary.
• Preserve production and user data. Inspect the exact account, environment, deployment, and data target before writes. For data changes, inspect a dry run or equivalent migration plan and validate recovery before an effect that could lose or corrupt data. Prefer additive, backward-compatible migrations and bounded batches. Record intent, use idempotency or conditional writes, and reconcile uncertain results before retrying. Verify deployed identity, health, and relevant data invariants after delivery. Routine delivery never authorizes resetting, truncating, dropping, or overwriting user data; stop the unsafe operation if preservation or recovery cannot be established.
• Keep delivery gates proportional to the failure they prevent. Prefer required checks on the current integration candidate, independent agent review, and atomic or conditional integration. Add a merge queue or another approval stage only for a demonstrated coordination or safety need. Replace redundant queues, serial waits, and duplicate checks through reviewed policy changes while retaining evidence for the integrated result.
• Do not cap agent count merely to reduce fan-out. Parallel reasoning and independent implementation lanes remain desirable.
• Prefer bounded subagents in the current task for research, review, diagnosis, and focused checks when they can safely share one working tree. A separate task or worktree is warranted for independently deliverable divergent edits, an intentionally isolated verification tree, or a different environment.
• Give each focused check one worker owner. The integrator reviews the diff and reported evidence, repeating a focused command only when the tree changed, evidence is missing, or a repair invalidated it.
• Give each CI run, merge-queue item, provider operation, or deployment wait one waiter. Do not hold a compute lease while waiting on external state.
• Run the repository's aggregate/final gate once after convergence. Never use a receipt to skip a repository-required final replayed-tree or delivery gate. Where reviewed repository policy assigns complete required CI as the final source aggregate, verify the policy's scope, coverage/equivalence evidence, independent impact review, and fresh exact-head, current-base CI result. Keep relevant focused local checks and separate local, native, coupled-run, live, and installation acceptance; do not add a duplicate local aggregate. Diagnose observed failures and stalls independently of a passing CI result. Use the local aggregate when the repository requires it or CI equivalence is uncertain.
• The host scheduler is an outer layer. Jungle and Oompa keep their repository schedulers underneath it; invoke oompa-host-run only around top-level commands. Nested oompa-host-run calls inherit the outer lease and do not acquire again.
• Keep roots and integrators on the caller's selected model. Bounded independent workers may use the installed oompa-worker or oompa-routine profiles when the task merits them; measure repair rate rather than assuming cheaper is better.
• This baseline is local-only. Do not create, configure, or route work to Codex cloud through this skill.

Capability lanes

• Ordinary: research, review, edits, and narrow checks. Share the current task worktree when safe and normally do not acquire a host lease.
• Heavy compute: broad builds and repository gates. Use the compute lane with heavy or exclusive mode.
• Browser auth: work that needs the user's signed-in browser, a fixed port, a dev server, or Chromium. Keep it on this machine, assign one owner, and use the browser-auth lane. Use exclusive mode for a fixed-port or heavyweight suite.
• Mac native: Xcode, Simulator, Keychain, signed-app, or other macOS-only work. Keep it on a Mac, assign one owner, and use the mac-native lane.

The browser and Mac lanes each serialize their scarce capability while still sharing the weighted compute capacity. A nested wrapper must be covered by the outer lane; choose the top-level lane correctly instead of escalating it inside an existing lease.

Plugin 0.4.6 adds bounded wait updates after 15 seconds and then every 30 seconds, plus a private local status and handoff channel. waiting-compute can already hold the browser capability, so finish that bounded command before releasing it. Do not keep a browser wrapper open for unrelated work between settled sessions. The status command is the supported projection for Slopcamera and other local callers; they must not inspect scheduler files. The projection is advisory and partial, with availability and custody always unknown. A crashed wrapper can leave descendants holding the real lease. Only the unchanged scheduler decides admission and release. OOMPA_LOCAL_EFFICIENCY_QUEUE=off disables this wrapper's observation channel and progress updates without changing its lease or telemetry. If dead observation sockets accumulate, oompa-host-queue --prune-stale --json removes only old, private, unchanged socket endpoints with unreachable connections. Registration performs the same bounded cleanup near its endpoint limit. Status reads never repair state, and observation cleanup never touches scheduler leases or establishes free capacity.

For an indivisible aggregate that requires macOS, such as Slopcamera bun run check, use exclusive mode on mac-native when its Chromium work is an owned fixture with a fresh profile and loopback server. Exclusive reserves all common compute capacity. This mapping admits no personal authenticated browser, shared fixed server, or nested cross-lane acquisition. Separate browser-only gates retain browser-auth.

For non-interactive macOS and Linux runs, the wrapper supervises a dedicated child process group and forwards HUP, INT, QUIT, and TERM to the whole group. An interactive TTY preserves its controlling terminal and receives best-effort leader signaling so an intentional 2FA prompt still works. Do not detach a background server from scheduler custody.

Resource modes

Use shared for one narrow check, heavy for production builds and ordinary repository-wide checks, and exclusive for full monorepo validation, native packaging, capture hardware, or fixed-port browser suites.

Submit exclusive work only after its inputs converge. Strict FIFO prevents starvation but can strand spare permits behind a waiting all-permit claim. If that happens ahead of a known finite shared/heavy backlog, only the exclusive claim's owner may cancel it before admission and requeue the identical command after the backlog drains. Never interrupt an admitted command just to reorder the queue, and never run its child outside the scheduler.

Known mappings:

• Jungle check:affected: heavy; Jungle full check: exclusive.
• Oompa check: exclusive compute, with the unchanged bun run check child. Its package tests share the machine-wide process-recovery journal, so parallel heavy leases can still contend across checkouts. Production builds: heavy; native package work: exclusive on the applicable capability lane.
• Personal template and Tiff full check/build: heavy.
• Narrow file or package tests: normally unscheduled, except process-custody or recovery checks that require the scheduler.

The wrapper runs the original public command unchanged. It does not substitute a weaker check.

Each top-level scheduler attempt appends one bounded local telemetry record when storage is available. A pre-admission scheduler error or catchable cancellation has no admission timestamp or run duration; cancellation is recorded before the waiting claim is released. Records contain timestamps, lane, mode, safe label, program label, permit counts, queue and run durations, an exit class, a hashed workspace identifier, and a command digest. They never contain raw argv, environment values, paths, transcripts, reasoning, or tool output. Telemetry is best effort and never changes the child command's result.

Host-access boundary

The machine-wide scheduler state intentionally lives outside an ordinary repository sandbox. Request reviewed host access for the top-level absolute oompa-host-run invocation on the first attempt. This also applies to focused Oompa process-custody and recovery tests: they exercise machine-scoped identity and journal locks even when their CPU cost is small.

If the wrapper reports OOMPA_HOST_ACCESS_REQUIRED and exits 77, retry the identical wrapper invocation once through Codex host-access approval or configured auto-review. Preserve the working directory and every argument. If the reviewed retry still returns 77, stop and diagnose the permission setup. Never bypass the wrapper by running its child directly, remove scheduler or recovery state, weaken fail-closed custody, or create an unconditional allow rule for oompa-host-run; it can wrap arbitrary child commands.

The bootstrap sets Codex to approval_policy = "on-request", approvals_reviewer = "auto_review", and default_permissions = ":workspace". It also manages a prompt-only Codex rule for the absolute installed wrapper. The rule makes every complete invocation reviewable but grants no permission. Codex loads configuration and rule files at task startup, so start a new task after installing or updating the baseline.

When the installed Claude Code is at least 2.1.83 and claude auto-mode config confirms that the CLI exposes a valid Auto-mode configuration surface, the bootstrap sets permissions.defaultMode = "auto" and inherits its built-in classifier rules through $defaults. Because explicit allow rules resolve before the Auto classifier, the bootstrap removes bare or universal whole-tool allows and every wildcarded Bash or PowerShell allow while preserving exact commands, path-bounded non-shell allows, and every deny. Claude may apply additional runtime filtering. It does not globally declare sibling repositories or the public npm registry trusted. The doctor reports the machine capability decision. If the CLI does not expose that surface, bootstrap leaves the ordinary permission setting untouched. Account, model, and organization eligibility is enforced by Claude Code when a session starts rather than attested by the configuration command; if that runtime gate refuses Auto mode, use the ordinary permission mode and never fall back to bypass permissions.

Validation receipts

oompa-validate fingerprints the Git HEAD, tracked diff, untracked file content and executable/link mode, working directory, exact command, Bun/Node versions, lockfiles, and caller contexts. It never follows untracked symlinks. Successful receipts live under the repository's Git common directory so linked worktrees can share exact evidence. Receipts and wrapper output retain only a safe operation label, program name, and command digest—not raw argv or context values. Reuse fails closed when the index contains skip-worktree or assume-unchanged entries, a populated gitlink/submodule, or an unsupported untracked file type.

Use --reuse --ttl-minutes=N only for deterministic focused commands. Force a real run after relevant environment or external state changes. Failed commands are reported for diagnosis but never reused as success.

Complete-history CI

A complete-history policy is not permission to fetch every live branch. Start from the exact governed SHA, disable credential persistence, and explicitly fetch only the fully qualified branch, tag, or exact-SHA refs the policy owns. Enumerate refs immediately afterward and reject any unexpected ref before the history scan. Keep rev-list --all or the repository's equivalent complete scan over that governed ref set.

Use oompa-ci-ref-audit as a conservative review aid. A broad fetch without a complete-history consumer is informational, and a complete-history consumer with an explicit governed ref set is compliant. Do not rewrite release history fetches mechanically; tags and the stable branch may both be required inputs.

Cleanup safety

Size is a discovery signal, not deletion authority. A removable worktree must be registered, present, clean including untracked and ignored files, free of skip-worktree and assume-unchanged index flags and populated gitlinks, neither primary nor the invoking worktree, explicitly named, and merged into an exactly fetched, fully qualified remote target. The cleanup script validates the full manifest before deletion and revalidates every target at action time. It never forces removal or deletes branches.

Treat unregistered temporary directories, Codex transcripts, application databases, credentials, private corpora, archives, and dirty worktrees as user state. Never sweep a temporary-path prefix.

At task closeout, record the applicable final branch, pull request, checks, merge, release, deployment, and production readback. Archive only a conclusively finished task; silence is not completion evidence. In the Codex app, archiving a completed managed-worktree task lets the app snapshot and reclaim its managed checkout. Permanent worktrees still require their own guarded cleanup.

Machine standard

bootstrap.ts manages one marked block in global Codex AGENTS.md, three top-level Codex permission settings, one marked block in global Claude CLAUDE.md, Claude's Auto-mode default, bounded environment, and broad-allow cleanup, two optional CLI profiles, a prompt-only host-access rule, a minimal private scheduler runtime, and convenience commands. It preserves unrelated TOML, JSON, Markdown, and rule content, leaves exact profile symlinks intact, and refuses unsafe targets. Use --check in automation and after plugin upgrades.

The Oompa repository marketplace is the cross-machine source of truth. Upgrade the marketplace and reinstall the plugin, then rerun bootstrap and start a new Codex task so the refreshed skill is discovered.