accelerate-local-work

AtomLane: Accelerate Local Work

AtomLane parallelizes only what is proven safe. Preserve task semantics first:

parallelism is legal only when the compiled

control flow, effects, resources, and authorization boundaries prove it safe.

Perform a cheap preflight

Use this skill when at least one condition holds:

• A composite command, package script, Make target, Compose application, test

suite, or build pipeline may contain independent work.

• One meaningful operation repeats across independent inputs.
• A dependency graph has two or more potentially ready nodes.
• A numerical, image, signal, ML, video, compression, or custom-GPU operation

may use an Apple-silicon backend.

Skip it for conversation, web research, one quick command, tiny work dominated

by startup, or a known fully serial mutation. Evaluation should be cheap; the

possibility of parallelism alone does not authorize execution.

If the requested optimization requires changing a long-running Python program

rather than scheduling its existing commands, route to

$optimize-python-parallelism and python_parallel_advisor. Do not treat a

source rewrite preview as an executable atomic plan.

Identify the execution realm before compiling. Native Windows, one WSL distro,

and one Docker daemon are distinct resource and path spaces; never mix them in

one plan without an explicit bridge. On native Windows Preview, use exact argv

atoms or the whole-file powershell_file adapter. POSIX shell, package-script,

Make-recipe, and Compose lowering are not Windows semantics and must fail

closed. Do not lower inline PowerShell or cmd/.bat syntax.

Compile once, execute the exact plan

For local execution covered by this skill, use this invariant:

atomic_task_plan -> immutable compiled_plan + plan_hash -> atomic_exec

1. Call atomic_task_plan before the first execution batch. Supply the active

project, task intent, and concrete entrypoints or candidate operations known

at that point. Use scenario_plan first only when an unfamiliar multi-stage

project, preset optimization profile, or explicitly requested trace evidence

would materially improve planning. For one concrete pytest suite, prefer

test_suite_plan; it is a thin frontend that returns the same standard

immutable plan and does not create a separate execution path.

1. Inspect the returned blockers, diagnostics, effect certainty, native

delegates, resource plan, estimated benefit, and plan_hash. Do not execute

a plan that reports an unresolved safety blocker.

1. Treat the complete return value as compiled_plan. Pass that exact object

and its hash to atomic_exec:

   compiled = atomic_task_plan(...)
   atomic_exec({
     "compiled_plan": compiled,
     "plan_hash": compiled["plan_hash"]
   })

1. Do not reconstruct, trim, reorder, or edit the compiled object. Do not

change argv, cwd, environment, effects, edges, resources, executor choice,

or retry policy between planning and execution. Optional execution-only

output caps and, for ordinary work, serial_baseline_seconds may be supplied

outside the plan. Native pytest pools reject bare seconds and use only the

attested baseline protocol below.

1. If the task, entrypoint, project evidence, resource assumptions, or desired

behavior changes, discard the old result and call atomic_task_plan again.

A hash mismatch or stale precondition must fail rather than fall back to an

unverified command.

Read [references/atom-ir.md](references/atom-ir.md) before handling a composite

shell/package entrypoint, Make or Compose graph, native test/build executor,

long-running service, formal benchmark, or proposed split/fusion. It defines

the effect, edge, lifecycle, transformation, and plan/hash contract.

Preserve exact control flow

Exact mode is the default:

• Preserve hard, success, failure, order, data, stream,

after_ready, after_healthy, after_completion, and finally as distinct

relationships. Keep resource conflicts as leases or deterministic scheduler

serialization, not fabricated source control flow.

• a && b is success-gated; a || b is failure-gated. Shell sequences and

recipe lines are not a bag of independent commands.

• Do not speculatively run later diagnostics merely because they appear

read-only. That changes fail-fast behavior unless the user explicitly asks

for a non-equivalent run-all diagnostic mode supported by the planner.

• A daemon dependent waits for a declared ready or healthy event, not for the

daemon to exit.

Never interpret an unknown effect as no effect. Unknown-effect atoms cannot be

parallelized, reordered, fused, cached, or automatically retried. Preserve the

original authorized entrypoint as one opaque serial compound atom only when

the planner proves that this retains its original boundary; otherwise stop and

report what evidence is missing. Do not repair uncertainty by guessing paths

or setting a side-effect flag to false.

Delegate concurrency to semantic owners

Follow the executor and native-delegate decisions in compiled_plan:

• Let a sound Make graph own jobs through its jobserver. Recipe lines remain

ordered, prerequisites are unordered unless constrained, and inferred file

dataflow may add a safe edge when the source graph is incomplete.

• Let Docker Compose resolve profiles, service closure, health/completion

conditions, one-shot jobs, and long-lived services. Prefer one compatible

Compose operation over unrelated compose up processes.

• Let Vitest, Jest, pytest, compiler drivers, BuildKit, and similar tools use

their native worker pools when their output and failure semantics are safer

than external sharding.

• Shard only when outputs, reports, caches, databases, and temporary paths are

isolated and the plan contains a deterministic merge.

A native delegate is a plan contract, not permission to recreate its inner

jobs with legacy executors. If the returned plan is not execution-eligible

because this installed executor cannot honor its delegate, lifecycle, or event

semantics exactly, stop and report the blocker. Do not translate it into

parallel_exec, parallel_map, or parallel_dag.

Budget native inner workers together with outer concurrency. Do not multiply

Vitest, BLAS, BuildKit, compiler, or GPU worker pools until the host is

oversubscribed. Repeated tiny atoms should be fused or delegated to a native

batch when doing so preserves control flow and reporting.

Compile pytest through its native owner

When a pytest suite contains many independent cases—for example, 100 decoupled

tests—use test_suite_plan to create one resource-bounded pytest-xdist pool.

Do not translate testcases into 100 external atoms. Supply an exact pytest

runner prefix using Python's module form (for example,

[python, -m, pytest]), selectors/arguments, the intended worker count or auto, and

complete declared file and non-file effects. Set independence_declared=true

only after checking fixture, ordering, database, port, and shared-resource

semantics; it is required for a multi-worker plan. Add project-local

snapshot_paths that cover every semantically relevant selected test, source,

helper, project-local plugin, and conftest; AtomLane separately binds the effective pytest

config snapshot. Set baseline_source_closure_declared=true only after checking

that closure. Both the declaration and AtomLane's bounded static coverage check

are required before a serial run can issue baseline evidence. The static check

cannot discover every dynamic import or dynamically loaded plugin, so treat the

declaration as a caller assertion, not proof of complete semantic closure.

Installed pytest/xdist distributions and plugins outside the project are not

content-attested; keep that caller-trusted environment unchanged between a

serial baseline and its parallel comparison.

The planner must not run pytest --collect-only, import test modules, install

pytest-xdist, infer independence from a case-count hint, or guess missing

effects. AtomLane owns -n/--numprocesses,

--dist, --basetemp, and JUnit output; remove conflicting caller or

PYTEST_ADDOPTS copies and replan rather than overriding the compiled argv. It

binds and snapshots the effective project-local pytest config with -c, while

preserving and hash-binding valid config addopts and PYTEST_ADDOPTS. Supply

config_path when discovery is ambiguous. Preserve a plain pyproject.toml

chosen only by pytest 8.4's rootdir fallback as the distinct, hash-bound

fallback_pyproject selection kind, and require runtime revalidation to prove

that it remains free of pytest configuration. On Python 3.10, parsing

pyproject.toml requires importable tomli. JUnit and base-temp paths must not

overlap source/config snapshots, the runner executable, or each other. Keep an

explicit JUnit path outside all selected collection directories across every

suite in the plan, or omit it for the unique system-temp default. Apply the same

case-folded, Unicode-NFC overlap identity at compilation and runtime in both

cross-suite directions, together with physical ancestor/file identities that

collapse firmlink and mount aliases. On Windows, reject report paths with trailing

spaces/dots, alternate streams, reserved device components, drive/root-relative

spellings, or device namespaces before filesystem resolution. Use the independent-case worksteal default;

choose file/scope/group affinity only when fixtures require it.

Execution holds sorted, non-blocking cross-process leases for every JUnit and

base-temp path through report parsing. If another run owns one, fail fast and

recompile for fresh generated paths or choose a distinct junit_path; do not

wait and include queue time in a savings comparison. Lease the normalized path,

physical parent-plus-basename, and existing target; recompute the complete key

set while held. On native Windows, derive the lease root from the profile

directory bound to the current process token rather than profile environment variables.

Positional selectors, config testpaths/pythonpath, and explicit

snapshot_paths must already resolve directly inside the project without a

symbolic-link/reparse alias and are revalidated before launch. Any link found

inside an audited collection tree makes that run ineligible to issue serial

baseline evidence. AtomLane injects

--confcutdir=<project_root> so parent-directory conftest.py files outside

the declared project cannot execute. AtomLane explicitly loads

xdist even when plugin autoloading is disabled; it disables the shared pytest

cache provider and rejects cache-dependent selection flags. Write unknown

third-party pytest options that take values as --option=value; a separated

value is ambiguous with a positional selector and must not be used.

Direct pytest/py.test console scripts are not accepted. AtomLane

hash-attests and revalidates the selected Python interpreter, clears

PYTHONPATH/PYTHONHOME/PYTHONOPTIMIZE, and rejects

project/config-pythonpath candidates that could shadow pytest or xdist or

inherited optimization settings that could remove ordinary assertions; the caller remains responsible for

trusting the selected environment and its installed packages.

pytest-xdist is required for both the serial-baseline and multi-worker routes.

If it is unavailable at execution, report the dependency failure;

do not install it unless the user separately authorizes dependency changes.

Version 0.16 release evidence covers macos-14 and windows-2025, CPython

3.10–3.13, pytest 8.4.2, and pytest-xdist 3.8.0. Treat other versions as

unverified by this release rather than silently broadening the claim.

Treat the chosen worker count as a CPU-capacity claim, not affinity.

pytest-xdist and the OS schedule workers; AtomLane does not pin them to cores.

Report native_workers_configured as configured evidence and

outer_peak_concurrency as observed outer scheduling. Never convert either

into native_workers_observed; leave that unavailable without compatible

runtime instrumentation, and leave native-pool parallel efficiency unavailable

for the same reason. A case-count hint is also not collection evidence. It may

cap worker_count=auto, but it never proves case independence.

For a measured native-pool comparison, execute the exact same selection first

with worker_count=1. Only a successful, non-skipped run with fresh,

non-empty, passing, counter-consistent JUnit evidence and the required explicit

source closure, baseline_source_closure_declared=true, and a passing bounded

static coverage check may return session-bound serial_baseline_evidence; pass

that object unchanged to the multi-worker atomic_exec. This attests execution

over the caller-declared closure, not independently proved semantic closure. The

parallel JUnit must be fresh and match the attested testcase identities and

outcomes. If no compatible attestation is available, only complete and

runtime-plausible testcase timings from that fresh JUnit may be used as an

explicitly labeled estimate. Display it for the current run and record it only

in the estimated bucket; never credit it to the primary cumulative total.

Respect resources and evidence fences

The plan must account for file access modes and sidecars, Git state, database

scope, ports, containers, volumes, devices, external accounts, accelerators,

memory, and native worker capacity. Read/read sharing is usually compatible;

write/read and write/write overlap require ordering or isolation.

Formal timing, append-only evidence, post-candidate bytecode, and similar

project policies are first-class resources or prohibitions. Independent output

paths do not make a timing-sensitive benchmark safe to overlap. Relax such a

fence only when the user requests a correctness-only replay and the plan marks

the output ineligible for the original performance claim.

Parallelism changes timing, not permission. It does not authorize new commands,

mutations, external actions, retries, or destructive cleanup. Retry only atoms

the compiled plan marks idempotent and retryable.

Match the current host

Use host_resource_plan and the fresh resource observations embedded by the planner. An explicit

concurrency value is a ceiling, not an override of safety limits. Interactive

mode should retain CPU and memory headroom and reduce work under existing load,

battery use, Low Power Mode, memory pressure, or thermal pressure.

For atomic_exec, ready atoms are evaluated as a batch, not as unrelated

one-at-a-time decisions. The executor registers the invocation in the shared

host scheduler and admits native-host worker, CPU, memory, and accelerator

tokens across concurrent Codex tasks. One session may borrow unused capacity;

competing sessions receive a soft fair share. Use throughput when the user

explicitly prioritizes full-machine background throughput, balanced for a

mixed foreground/background run, and the default interactive mode while the

user is actively working. Throughput may use the complete detected CPU pool,

but thermal, power, memory, external-load, and immutable-plan ceilings still

apply. Docker/WSL resources remain separate daemon/VM realms and are not charged

as if they were directly contained native-host processes.

Runtime capacity is refreshed while a long plan runs. It may contract or recover

inside the compiled ceiling; it may never exceed that ceiling. A corrupt or

foreign shared scheduler ledger is an execution blocker, not permission to fall

back to uncoordinated fan-out.

On native Windows, every target runs below a kill-on-close Job Object. Optional

cpu_rate_percent and memory_limit_mb limits apply Job-wide.

max_processes is available only with terminal_mode: pipes, where the Job

active-member ceiling includes the verified supervisor and must be at least 2;

it is not a target-only allowance. Combining it with ConPTY fails closed because

console-host Job membership is not yet proven. If Job assignment

fails, do not start target code and do not fall back to killing only the direct

child. Use terminal_mode: conpty only when output-side terminal behavior is

required; it combines stdout/stderr into one VT stream. Explicit ConPTY stdin

fails before target creation because the Preview has no verified terminal-input

and EOF contract; use pipes for bounded stdin and observable EOF semantics.

Ordinary tasks retain separate pipes, while MCP/live-runner heartbeats still

provide real-time elapsed, state, and saving updates.

For numerical or media implementation work, call mac_accelerator_plan before

choosing an Apple backend. On a non-macOS host it is explicitly unavailable:

• Accelerate/BNNS for suitable CPU-vector math, DSP, image, and neural-network

operators.

• Core ML with all compute units for compatible inference.
• MLX or PyTorch MPS for compatible tensor workloads.
• Metal or MPSGraph for large custom data-parallel operators.
• VideoToolbox-backed codecs for supported media work.

Hardware availability does not prove that a program uses it. The invoked code

must implement or expose the backend. GPU, ANE, media engines, unified memory,

and memory bandwidth are shared; accelerator fan-out is normally low.

For container budgeting, use container_resource_plan when useful, but keep

the generated budgets inside a newly compiled plan. On Docker Desktop, allocate

from the identified Linux VM/daemon envelope. A cpuset identifies VM vCPUs,

not stable physical host cores. Native Windows, WSL, and the Docker Linux VM

must never share one inferred capacity. Windows-container or unavailable-daemon

results remain advisory rather than directly applicable.

Keep long execution visibly live

For a plan expected to run longer than ten seconds, live display is mandatory.

Do not await atomic_exec as one blocking MCP call in Codex Desktop.

1. Place the exact atomic_exec arguments—unchanged compiled_plan, matching

plan_hash, and only documented execution-only options—in a JSON file under

the active workspace's work/ directory.

1. Resolve this installed plugin's root and run:

   python3 scripts/live_runner.py --mode atomic --input <absolute-json-path>

through exec_command in a PTY, with the initial yield no longer than one

second.

1. Poll the session with write_stdin about every five seconds. After each

poll, send a short user-visible update with elapsed time,

running/ready/completed/failed counts, and current estimated time saved. For

a native pytest pool, also show configured workers and any case-count hint,

while describing savings as pending until a baseline or fresh JUnit timing

report is available. When present, retain the live host-session count and

globally reserved worker-slot evidence rather than hiding cross-task

contention.

1. Continue until LIVE_RESULT_JSON= and the process exit code arrive. Do not

substitute a hand-built legacy exec/map/DAG payload for the compiled atomic

plan.

For shorter work, a direct atomic_exec call is acceptable when it does not

hide meaningful progress.

Verify and report the result

A successful scheduler call proves transport success, not task success.

Inspect every atom's status, return code, stderr, timeout, skip reason, and

truncation flags. Downstream work whose typed dependency failed must not run.

Start the final execution report with the returned compact indicator, such as

⚡ 并行｜峰值 8 路｜估算 5.42×,

→ 串行｜峰值 1 路｜估算 0.98×, or the native-pool form

⚙️ 原生并行｜配置 8 workers｜外层峰值 1 路｜本次节约待基线. Then report:

• elapsed time and observed peak concurrency;
• failed and skipped atom IDs and output locations;
• time_saved_seconds plus its measured/estimated provenance for this

invocation;

• ledger_credit_eligible, ledger_credit_recorded, and

credited_time_saved_seconds; and

• primary cumulative_saved_seconds (measured plus retained legacy

unclassified values) separately from cumulative_estimated_saved_seconds.

For ordinary work, label a supplied serial_baseline_seconds comparison

measured; otherwise label multiplier and savings estimated from observed

non-skipped atom durations. Native pytest pools reject that bare value and use

only a matching, closure-declared, statically checked, session-attested

worker_count=1 baseline for a measured comparison. They may use the sum of

complete, runtime-plausible timings from a fresh, passing, counter-consistent

JUnit report only as an explicitly labeled estimate. Without either, keep

per-run savings pending and do not credit cumulative savings. Never rerun

side-effecting work merely to benchmark it, and never present an estimate as a

controlled benchmark. Ledger v2 retains pre-v2 totals as

legacy_unclassified, never relabels them as measured, and must not overwrite

an invalid existing ledger.