@pikaa-ai/pikaa 0.3.1 → 0.3.4

package/skills/get-available-resources/references/resource_semantics.md

@@ -1,206 +0,0 @@
-# Resource Semantics
-
-Research and behavior cut-off: **2026-07-23**. See
-[`sources.md`](sources.md) for the official documentation used.
-
-## Core rule: inventory is not entitlement
-
-Never treat a host-wide count as a promise that the current process can use it.
-Interpret usable resources as the intersection of independently observed
-constraints:
-
-1. host inventory;
-2. process affinity or processor-group scope;
-3. cgroup/container constraints;
-4. scheduler allocation;
-5. accelerator visibility and device permissions; and
-6. application runtime compatibility.
-
-Missing evidence means **unknown**, not unlimited. Scheduler variables can
-describe an allocation without proving that affinity or cgroup enforcement is
-enabled. Conversely, a cgroup or affinity mask can be stricter than the
-scheduler request.
-
-## CPU
-
-### Physical and logical CPUs
-
-- A logical CPU is an operating-system scheduling unit. Simultaneous
-  multithreading can expose multiple logical CPUs on one physical core.
-- A physical-core count describes topology, not the number of independent
-  workers the process may start.
-- `os.cpu_count()` and `psutil.cpu_count(logical=True)` are host/system
-  inventory. They can exceed the CPUs usable by the process.
-- `os.process_cpu_count()` (Python 3.13+) is process-aware. On supported
-  platforms, affinity APIs provide a more explicit process constraint.
-- On Windows systems with multiple processor groups, a system-wide logical
-  count and one process/thread group's usable count can differ.
-
-The detector reports host logical and physical counts separately. It never
-derives physical cores from a logical count.
-
-### Affinity, cpusets, and quotas
-
-- Process affinity limits the logical CPUs on which a process may execute.
-- Linux `cpuset.cpus.effective` reports CPUs actually granted after parent
-  constraints. The requested `cpuset.cpus` can differ.
-- `/proc/self/status` exposes `Cpus_allowed_list`, but the detector prefers
-  affinity APIs and cgroup effective cpusets.
-- cgroup v2 `cpu.max` is `$MAX $PERIOD`. `max` means no local bandwidth limit.
-  A finite ratio is CPU-time capacity, possibly fractional; it is not a core
-  topology count.
-- Parent cgroups also constrain children, so the detector takes the most
-  restrictive finite ancestor quota.
-
-For a `cpu.max` ratio of 1.5, the snapshot reports
-`capacity_cores: 1.5` and a conservative CPU-bound worker ceiling of 1. A
-workload may choose more threads for latency hiding, but it should expect
-throttling and must not describe those threads as 1.5 physical cores.
-
-### Python worker pools
-
-- Current Python `multiprocessing.Pool` and `ProcessPoolExecutor` defaults use
-  `os.process_cpu_count()` when available.
-- Python 3.14 no longer uses `fork` as the default start method on any platform.
-  Code that depends on a particular start method must request it deliberately.
-- Process workers do not make each worker's native-library threads disappear.
-  BLAS/OpenMP threads multiplied by process workers commonly oversubscribe an
-  allocation.
-- Windows `ProcessPoolExecutor` has a documented maximum of 61 workers.
-
-Use the workload planner's worker and threads-per-worker values as conservative
-ceilings, then benchmark a real representative workload. Do not run a synthetic
-stress test merely to discover capacity.
-
-## Memory
-
-### Host and effective memory
-
-- `psutil.virtual_memory().total` and `.available` describe system-visible
-  memory, not necessarily the process limit.
-- Linux `/proc/meminfo` `MemAvailable` is the standard-library fallback for a
-  host-availability estimate.
-- cgroup v2 `memory.current` is current cgroup usage.
-- `memory.high` is a throttle/reclaim pressure boundary. Exceeding it does not
-  itself invoke the cgroup OOM killer, and the value can be breached.
-- `memory.max` is the hard cgroup limit. If usage cannot be reduced at that
-  boundary, the cgroup OOM killer can run.
-- Parent memory limits are hierarchical. Shared ancestor usage can reduce what
-  remains for a child, so effective remaining memory is the minimum finite
-  `limit - current` observed through the ancestor chain.
-- Slurm memory variables describe requested/allocated memory, but strict
-  enforcement depends on site configuration.
-
-The detector keeps host total/available values, cgroup values, scheduler values,
-and the conservative effective values distinct. A point-in-time "available"
-value can change immediately and is not a reservation.
-
-### macOS unified memory
-
-On Apple silicon, CPU and integrated GPU share unified memory. Do not add a
-fictional GPU VRAM amount to system RAM. The snapshot marks the memory model as
-`unified_cpu_gpu` and leaves dedicated GPU memory null. Metal framework support
-and model/operator support still require application-specific checks.
-
-## Accelerators
-
-Accelerator usability has separate layers:
-
-1. **Hardware or management visibility** — a management query returns a device.
-2. **Allocation visibility** — scheduler and named visibility variables permit
-   a device or a subset.
-3. **Device permission** — the process/container can open the required device
-   interfaces.
-4. **Driver/runtime compatibility** — driver, CUDA/ROCm/Metal runtime, and
-   framework versions are compatible.
-5. **Workload compatibility** — the requested operation and data type are
-   implemented on that backend.
-
-`nvidia-smi` success confirms NVIDIA management visibility only. It does not
-prove that CUDA libraries exist or are compatible. NVIDIA documents driver and
-runtime compatibility as a separate requirement.
-
-AMD SMI or ROCm SMI success likewise does not prove HIP/ROCm runtime usability.
-New deployments should prefer `amd-smi`; `rocm-smi` is retained as a read-only
-fallback. On Linux, AMD recommends `ROCR_VISIBLE_DEVICES`; on Windows it
-recommends `HIP_VISIBLE_DEVICES`.
-
-An Apple integrated GPU is a Metal candidate, not a CUDA GPU. AMD GPUs are ROCm
-candidates, not CUDA GPUs. Neural engines, TPUs, FPGAs, and other accelerators
-must also remain distinct from CUDA devices if another inventory source adds
-them.
-
-The detector reads only these accelerator variable names and redacts their
-values:
-
-- `NVIDIA_VISIBLE_DEVICES`
-- `CUDA_VISIBLE_DEVICES`
-- `ROCR_VISIBLE_DEVICES`
-- `HIP_VISIBLE_DEVICES`
-
-Counts derived from those values are only upper bounds. Environment variables
-are not a security boundary and can be reset by an application; device
-namespace/cgroup controls are stronger isolation.
-
-## Slurm and other schedulers
-
-The detector allowlists named Slurm variables and never dumps the environment.
-It records field names, parsed bounded counts, and memory quantities, but not
-job IDs, GPU UUIDs, node names, submit hosts, or paths.
-
-Important scopes:
-
-- `SLURM_CPUS_PER_TASK`: requested CPUs per task; suitable as a per-process
-  upper bound for one task process.
-- `SLURM_CPUS_ON_NODE`: CPUs allocated to the current batch step on the node;
-  it can be shared among tasks.
-- `SLURM_JOB_CPUS_PER_NODE`: a per-node allocation list, not a process count.
-- `SLURM_MEM_PER_CPU`: memory per allocated CPU. It becomes a per-task bound
-  only when CPUs per task is known.
-- `SLURM_MEM_PER_NODE`: shared per-node memory upper bound.
-- `SLURM_GPUS_PER_TASK`: requested GPUs per task.
-- `SLURM_GPUS_ON_NODE`: GPUs allocated to the batch step on the node.
-
-Slurm CPU confinement requires site configuration such as task affinity or
-`task/cgroup` with core constraints. Memory requests are not strictly enforced
-unless the site enables an enforcement mechanism. Use affinity and cgroup
-observations as enforcement evidence; do not trust visible node inventory.
-
-For other schedulers, use their documented allocation API or variables and the
-same rule: allocation metadata and kernel enforcement are different facts.
-Do not guess from generic environment names.
-
-## Containers and OCI
-
-Docker containers have no CPU or memory limit by default. When configured,
-Docker maps CPU and memory flags to cgroup controls. OCI runtime configuration
-also defines CPU, memory, and device constraints.
-
-Inside a container:
-
-- host inventory may remain visible;
-- a CPU quota can be smaller than the visible CPU set;
-- a cpuset can be smaller than the quota's apparent capacity;
-- cgroup memory can be smaller than host RAM;
-- GPU management tools can see a different set from the application runtime;
-  and
-- mounted-volume capacity can differ from writable quota.
-
-Always report observed cgroup controls and uncertainty. A container marker
-without a finite cgroup value does not imply a finite limit.
-
-## Disk
-
-Capacity, free blocks, user-writable blocks, path permission, filesystem quota,
-and actual ability to complete a write are different:
-
-- capacity is the filesystem's total size;
-- free blocks can include blocks reserved from an unprivileged user;
-- POSIX `f_bavail` estimates blocks available to the current user;
-- `os.access(..., os.W_OK)` is a non-writing permission check, not proof that a
-  future write will succeed;
-- project/user quotas and remote storage policies can be stricter than block
-  counts.
-
-The detector does not create a probe file. It redacts the absolute working path
-and labels the scope as the working filesystem.

package/skills/get-available-resources/references/snapshot_schema.md

@@ -1,172 +0,0 @@
-# Snapshot Schema 1.1
-
-The detector emits one JSON object with sorted keys. Values vary by observation,
-but field names and meanings are stable for schema `1.1`.
-
-## Top-level contract
-
-- `schema_version`: `"1.1"`.
-- `snapshot_kind`: `"effective_resource_snapshot"`.
-- `observed_at`: UTC observation time.
-- `completeness`: `complete`, `complete_with_informational_notes`, or
-  `partial`.
-- `platform`: OS family, architecture, and Python version. Hostname is omitted.
-- `privacy`: explicit redaction flags.
-- `cpu`, `memory`, `disk`, `accelerators`: resource observations.
-- `cgroup_v2`, `container`, `scheduler`: execution-context observations.
-- `warnings`: bounded sorted warning records.
-- `provenance`: bounded sorted source/status records.
-
-Null means unavailable, not zero and not unlimited. Zero is used only when a
-source explicitly establishes zero (for example, a named accelerator visibility
-variable that hides all devices).
-
-## CPU
-
-`cpu.host`:
-
-- `logical`: system-visible logical CPUs.
-- `physical`: system-visible physical cores, or null. This value is not
-  converted into an effective process count.
-
-`cpu.process`:
-
-- `affinity_logical`: size of the current affinity set when supported.
-- `python_available_logical`: `os.process_cpu_count()` when supported.
-
-`cpu.cgroup_v2`:
-
-- `cpuset_logical`: count from `cpuset.cpus.effective`.
-- `quota_cores`: most restrictive finite ancestor `cpu.max` ratio. This may be
-  fractional.
-
-`cpu.effective`:
-
-- `capacity_cores`: minimum positive host/process/cgroup/scheduler capacity.
-- `worker_ceiling`: conservative bounded floor for CPU process workers.
-- `limiting_sources`: sources tied at that minimum.
-
-The effective value is intentionally not called a physical-core count.
-
-## Memory
-
-`memory.host` preserves system-visible `total_bytes` and `available_bytes`.
-
-`memory.cgroup_v2` preserves current-cgroup usage and hierarchical effective
-limits:
-
-- `current_bytes`
-- `available_bytes`
-- `high_bytes`
-- `max_bytes`
-
-`memory.effective`:
-
-- `hard_limit_bytes`: minimum of finite host total, cgroup hard limit, and
-  interpretable scheduler allocation.
-- `available_bytes`: minimum of host available, hierarchical cgroup remaining,
-  and scheduler upper bound.
-- `pressure_threshold_bytes`: cgroup `memory.high`; it is not relabeled as a
-  hard limit.
-- `hard_limit_sources` and `available_limiting_sources`: tied minimum sources.
-
-`memory.model` is `unified_cpu_gpu` on Apple silicon and `system_ram`
-otherwise. Unified GPU memory is not added again as dedicated VRAM.
-
-## Disk
-
-- `capacity_bytes`: total working-filesystem capacity.
-- `free_bytes`: filesystem free blocks.
-- `user_available_bytes`: user-available blocks where the OS exposes them.
-- `writable`: result of a non-writing access check.
-- `writability_check`: makes clear that no write probe occurred.
-- `scope`: `working_filesystem_path_redacted`.
-
-None of these values proves that a filesystem or project quota permits a write
-of the same size.
-
-## Accelerators
-
-`accelerators.devices` contains management-visible or explicitly
-platform-inferred candidates:
-
-- `vendor`: `nvidia`, `amd`, or `apple`.
-- `device_class`: keeps integrated and discrete GPU concepts distinct.
-- `backend_candidate`: `cuda`, `rocm`, or `metal`.
-- `management_query`: visibility evidence.
-- `device_permission`: `not_tested`; a query does not prove device-node access.
-- `runtime_compatibility`: `not_tested` in detector output.
-- `memory.model`: dedicated/HBM, unified, or unknown.
-- `local_index`: local query index; stable UUIDs and PCI addresses are omitted.
-
-`candidate_counts` is a query count, not a usable-device count.
-`candidate_upper_bounds` conservatively intersects query count with parsed
-visibility/allocation counts when available. `runtime_usable_devices` remains
-null because no framework runtime is loaded.
-
-`visibility_environment` includes only four allowlisted variable names. Raw
-values are never emitted.
-
-## Scheduler and cgroup
-
-`scheduler.fields_read` lists allowlisted Slurm names that were present.
-`scheduler.allocation` contains parsed bounded values and scopes.
-`scheduler.enforcement` remains `unknown`; variables alone do not prove
-confinement.
-
-`cgroup_v2.scope` says only `root`, `non_root`, `unknown`, or `not_applicable`.
-The cgroup path is not emitted.
-
-`container.detected` requires a known marker. A `cgroup_limit` can appear as
-evidence without asserting that the process is in a container.
-
-## Warnings and provenance
-
-Warnings use:
-
-```json
-{
-  "code": "STABLE_MACHINE_CODE",
-  "component": "cpu",
-  "message": "Human-readable, sanitized explanation.",
-  "severity": "info"
-}
-```
-
-Probe exception text, stderr, paths, hostnames, device UUIDs, and broad
-environment content are excluded.
-
-Provenance uses:
-
-```json
-{
-  "component": "cpu.process.affinity_logical",
-  "source": "os.sched_getaffinity",
-  "status": "ok"
-}
-```
-
-Possible status values include `ok`, `unavailable`, `absent`, `skipped`,
-`not_found`, `timeout`, `truncated`, `error`, and `parse_error`.
-
-## Validation and diff
-
-Validate:
-
-```bash
-python scripts/snapshot_tools.py validate resource-snapshot.json
-```
-
-Diff while ignoring `observed_at`:
-
-```bash
-python scripts/snapshot_tools.py diff before.json after.json
-```
-
-Use `--include-volatile` only when timestamp changes matter. Diff output is
-bounded to 512 changes.
-
-All helper inputs are regular, non-symlink JSON files no larger than 1 MiB.
-Output defaults to stdout. Explicit file output is restricted to a `.json`
-filename in the current directory, refuses overwrite unless `--force` is used,
-and is opened with private permissions.

package/skills/get-available-resources/references/sources.md

@@ -1,124 +0,0 @@
-# Official Sources
-
-Research cut-off: **2026-07-23**. Every URL below was consulted on that
-date. Undated living documentation is labeled "living docs"; a date in
-parentheses is the page/release date visible in the source.
-
-## psutil
-
-- [psutil 7.2.2 documentation](https://psutil.readthedocs.io/) — living docs.
-  Used for logical versus physical CPU counts, the warning that system CPU
-  count can differ from process-usable CPUs under affinity/cgroups/Windows
-  processor groups, `Process.cpu_affinity()`, `virtual_memory()`,
-  `swap_memory()`, and `disk_usage()`.
-- [psutil 7.2.2 on PyPI](https://pypi.org/project/psutil/7.2.2/) — current
-  stable package pin verified 2026-07-23.
-
-## Python
-
-- [Python `os` documentation](https://docs.python.org/3/library/os.html) —
-  Python 3.14.6 living docs. Used for `os.cpu_count()`,
-  `os.process_cpu_count()`, and `os.sched_getaffinity()`.
-- [Python multiprocessing](https://docs.python.org/3/library/multiprocessing.html)
-  — Python 3.14.6 living docs. Used for process-aware pool defaults and the
-  Python 3.14 start-method change.
-- [Python concurrent.futures](https://docs.python.org/3/library/concurrent.futures.html)
-  — Python 3.14.6 living docs. Used for `ProcessPoolExecutor` defaults,
-  Windows' 61-worker maximum, and `ThreadPoolExecutor` defaults.
-
-## Linux procfs and cgroup v2
-
-- [Linux kernel `/proc` filesystem documentation](https://docs.kernel.org/filesystems/proc.html)
-  — living kernel docs. Used for `Cpus_allowed` and
-  `Cpus_allowed_list`.
-- [Linux kernel cgroup v2 documentation](https://docs.kernel.org/admin-guide/cgroup-v2.html)
-  — living kernel docs; page history begins 2014-07-15. Used for
-  `cpu.max`, `cpuset.cpus.effective`, `memory.current`, `memory.high`,
-  `memory.max`, hierarchy, reclaim, and cgroup OOM behavior.
-- [Linux kernel cpuset documentation](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/cpusets.html)
-  — living kernel docs. Used to cross-check the interaction between affinity
-  masks and cpuset constraints.
-
-## Containers and OCI
-
-- [Docker resource constraints](https://docs.docker.com/engine/containers/resource_constraints/)
-  — living docs. Used for Docker's default lack of constraints, `--cpus`,
-  quota/period, cpusets, and memory controls.
-- [OCI Runtime Specification: Linux resources](https://specs.opencontainers.org/runtime-spec/config-linux/?v=v1.3.0)
-  — OCI Runtime Spec 1.3.0. Used for CPU, memory, cgroup, and device resource
-  semantics.
-
-## NVIDIA
-
-- [NVIDIA System Management Interface manual](https://docs.nvidia.com/deploy/nvidia-smi/index.html)
-  — living docs. Used for fixed `--query-gpu` fields and
-  `--format=csv,noheader,nounits`; NVIDIA notes that index ordering is not
-  stable, which is why snapshots do not claim a persistent identity.
-- [NVIDIA Container Toolkit specialized configurations](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html)
-  — living docs. Used for `NVIDIA_VISIBLE_DEVICES`, driver capabilities, and
-  runtime constraints.
-- [NVIDIA `CUDA_VISIBLE_DEVICES`](https://docs.nvidia.com/deploy/topics/topic_5_2_1.html)
-  — official deployment documentation. Used for CUDA application visibility.
-- [NVIDIA CUDA compatibility](https://docs.nvidia.com/deploy/cuda-compatibility/latest/why-cuda-compatibility.html)
-  — living docs. Used to distinguish management visibility from compatible
-  GPU, driver, CUDA runtime, and dynamically linked libraries.
-
-## AMD ROCm
-
-- [AMD SMI CLI tool](https://rocm.docs.amd.com/projects/amdsmi/en/docs-7.2.0/how-to/amdsmi-cli-tool.html)
-  — AMD SMI 7.2.0 docs. Used for read-only `list`/`static` JSON output and the
-  meaning of unavailable fields.
-- [ROCm SMI Python/CLI usage](https://rocm.docs.amd.com/projects/rocm_smi_lib/en/latest/how-to/use-python.html)
-  — living docs. Used for the legacy `rocm-smi` read-only fallback.
-- [ROCm GPU isolation techniques](https://rocm.docs.amd.com/en/docs-7.2.4/conceptual/gpu-isolation.html)
-  — ROCm 7.2.4 docs. Used for `ROCR_VISIBLE_DEVICES`,
-  `HIP_VISIBLE_DEVICES`, `CUDA_VISIBLE_DEVICES`, Docker device isolation, and
-  the warning that environment variables are not isolation for untrusted code.
-- [ROCm environment variables](https://rocm.docs.amd.com/en/latest/reference/environment-variables/index.html)
-  — living docs. Used for AMD's Linux/Windows visibility-variable
-  recommendations.
-
-## Apple
-
-- [Apple: Determining system capabilities](https://developer.apple.com/documentation/kernel/1387446-sysctlbyname/determining_system_capabilities)
-  — living Apple Developer docs. Used for `hw.logicalcpu`,
-  `hw.physicalcpu`, `hw.memsize`, performance levels, and the distinction
-  between logical and physical cores.
-- [Apple `sysctl(3)` manual](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/sysctl.3.html)
-  — archived official manual. Used to cross-check physical-memory fields.
-- [Apple Developer Technical Support: system_profiler and integrated/SoC memory](https://developer.apple.com/forums/thread/688443)
-  — Apple DTS response dated 2021-08-24. Used for parseable
-  `system_profiler` output and the warning that DIMM-style details do not map
-  cleanly to integrated or Apple silicon memory.
-- The fixed `system_profiler SPDisplaysDataType -json` and named `sysctl -n`
-  queries were smoke-checked locally on Darwin 25.5.0 on 2026-07-23. The
-  script never requests the full system profile.
-
-## Slurm
-
-- [Slurm `sbatch`](https://slurm.schedmd.com/sbatch.html) — living SchedMD
-  docs. Used for exact output environment-variable scopes:
-  `SLURM_CPUS_ON_NODE`, `SLURM_CPUS_PER_TASK`,
-  `SLURM_JOB_CPUS_PER_NODE`, `SLURM_MEM_PER_CPU`,
-  `SLURM_MEM_PER_NODE`, `SLURM_NTASKS`, and GPU variables. Also used for
-  the explicit warning that memory requests require configured enforcement.
-- [Slurm CPU Management Guide](https://slurm.schedmd.com/cpu_management.html)
-  — living SchedMD docs. Used for `task/affinity`, `task/cgroup`,
-  `ConstrainCores`, binding, and logical CPU/core allocation examples.
-- [Slurm `srun`](https://slurm.schedmd.com/srun.html) — updated
-  2026-07-14. Used for task confinement and GPU binding behavior.
-- [Slurm `scontrol`](https://slurm.schedmd.com/scontrol.html) — living docs.
-  Used for the read-only `scontrol show job` interpretation workflow.
-- [Slurm `sstat`](https://slurm.schedmd.com/sstat.html) — living docs. Used
-  for post-launch job-step accounting semantics.
-
-## Windows
-
-- [Microsoft: Processor Groups](https://learn.microsoft.com/en-us/windows/win32/procthread/processor-groups)
-  — living Microsoft docs. Used for the distinction between system logical
-  processors, physical cores, and processor-group scheduling.
-- [GetLogicalProcessorInformation](https://learn.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getlogicalprocessorinformation)
-  — living Microsoft docs. Used for logical/physical relationships and the
-  current-group limitation on systems over 64 logical processors.
-- [GetLogicalProcessorInformationEx](https://learn.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getlogicalprocessorinformationex)
-  — page dated 2023-03-06. Used for system-wide processor-group topology.

package/skills/get-available-resources/scripts/_common.py

@@ -1,190 +0,0 @@
-#!/usr/bin/env python3
-"""Shared, dependency-free safety and JSON helpers."""
-
-from __future__ import annotations
-
-import argparse
-import json
-import math
-import os
-import stat
-import sys
-from pathlib import Path
-from typing import Any
-
-SCHEMA_VERSION = "1.1"
-MAX_SNAPSHOT_BYTES = 1_048_576
-MAX_WORKERS = 1_024
-MAX_TASKS = 1_000_000_000
-MAX_BYTES = 1 << 63
-
-
-class ResourceToolError(ValueError):
-    """A concise, user-safe CLI error."""
-
-
-def json_text(value: Any) -> str:
-    """Serialize deterministic, standards-compliant JSON."""
-    try:
-        return (
-            json.dumps(
-                value,
-                allow_nan=False,
-                ensure_ascii=False,
-                indent=2,
-                sort_keys=True,
-            )
-            + "\n"
-        )
-    except (RecursionError, TypeError, ValueError) as exc:
-        raise ResourceToolError("result is not valid JSON data") from exc
-
-
-def _safe_output_path(raw: str) -> Path:
-    """Restrict writes to one explicit JSON filename in the current directory."""
-    if not raw or len(raw) > 255:
-        raise ResourceToolError("output must be a short JSON filename")
-    candidate = Path(raw)
-    if candidate.is_absolute() or len(candidate.parts) != 1:
-        raise ResourceToolError(
-            "output must be a filename in the current directory, not a path"
-        )
-    if candidate.name in {".", ".."} or candidate.suffix.lower() != ".json":
-        raise ResourceToolError("output filename must end in .json")
-    return Path.cwd() / candidate.name
-
-
-def emit_json(value: Any, output: str | None = None, *, force: bool = False) -> None:
-    """Write JSON to stdout or an explicit private local file."""
-    payload = json_text(value)
-    if output is None:
-        sys.stdout.write(payload)
-        return
-
-    destination = _safe_output_path(output)
-    try:
-        if destination.is_symlink():
-            raise ResourceToolError("refusing to write through a symbolic link")
-        flags = os.O_WRONLY | os.O_CREAT
-        flags |= os.O_TRUNC if force else os.O_EXCL
-        if hasattr(os, "O_NOFOLLOW"):
-            flags |= os.O_NOFOLLOW
-        descriptor = os.open(destination, flags, 0o600)
-        try:
-            if hasattr(os, "fchmod"):
-                os.fchmod(descriptor, 0o600)
-            with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
-                descriptor = -1
-                stream.write(payload)
-                stream.flush()
-                os.fsync(stream.fileno())
-        finally:
-            if descriptor >= 0:
-                os.close(descriptor)
-    except FileExistsError as exc:
-        raise ResourceToolError(
-            f"{destination.name} already exists; use --force to replace it"
-        ) from exc
-    except OSError as exc:
-        raise ResourceToolError(
-            f"could not write the requested output file ({exc.__class__.__name__})"
-        ) from exc
-
-
-def read_json_file(raw: str) -> dict[str, Any]:
-    """Read one bounded regular JSON file without following symlinks."""
-    path = Path(raw)
-    try:
-        if path.is_symlink():
-            raise ResourceToolError("refusing to read a symbolic link")
-        info = path.stat()
-        if not stat.S_ISREG(info.st_mode):
-            raise ResourceToolError("snapshot input must be a regular file")
-        if info.st_size > MAX_SNAPSHOT_BYTES:
-            raise ResourceToolError(
-                f"snapshot input exceeds {MAX_SNAPSHOT_BYTES} bytes"
-            )
-        with path.open("rb") as stream:
-            payload = stream.read(MAX_SNAPSHOT_BYTES + 1)
-        if len(payload) > MAX_SNAPSHOT_BYTES:
-            raise ResourceToolError(
-                f"snapshot input exceeds {MAX_SNAPSHOT_BYTES} bytes"
-            )
-    except ResourceToolError:
-        raise
-    except OSError as exc:
-        raise ResourceToolError(
-            f"could not read snapshot ({exc.__class__.__name__})"
-        ) from exc
-    try:
-        parsed = json.loads(payload)
-    except (RecursionError, UnicodeDecodeError, json.JSONDecodeError) as exc:
-        raise ResourceToolError("snapshot is not valid UTF-8 JSON") from exc
-    if not isinstance(parsed, dict):
-        raise ResourceToolError("snapshot JSON root must be an object")
-    return parsed
-
-
-def bounded_int(
-    value: Any,
-    *,
-    minimum: int = 0,
-    maximum: int = MAX_BYTES,
-) -> int | None:
-    """Return a bounded integer without accepting booleans or floats."""
-    if isinstance(value, bool):
-        return None
-    if isinstance(value, int) and minimum <= value <= maximum:
-        return value
-    return None
-
-
-def bounded_number(
-    value: Any,
-    *,
-    minimum: float = 0.0,
-    maximum: float = float(MAX_BYTES),
-) -> float | None:
-    """Return a finite bounded number without accepting booleans."""
-    if isinstance(value, bool) or not isinstance(value, (int, float)):
-        return None
-    number = float(value)
-    if not math.isfinite(number) or not minimum <= number <= maximum:
-        return None
-    return number
-
-
-def argparse_positive_int(
-    value: str,
-    *,
-    maximum: int = MAX_TASKS,
-) -> int:
-    """Argparse converter for bounded positive integers."""
-    try:
-        parsed = int(value, 10)
-    except ValueError as exc:
-        raise argparse.ArgumentTypeError("must be an integer") from exc
-    if not 1 <= parsed <= maximum:
-        raise argparse.ArgumentTypeError(f"must be between 1 and {maximum}")
-    return parsed
-
-
-def argparse_nonnegative_int(
-    value: str,
-    *,
-    maximum: int = MAX_BYTES,
-) -> int:
-    """Argparse converter for bounded nonnegative integers."""
-    try:
-        parsed = int(value, 10)
-    except ValueError as exc:
-        raise argparse.ArgumentTypeError("must be an integer") from exc
-    if not 0 <= parsed <= maximum:
-        raise argparse.ArgumentTypeError(f"must be between 0 and {maximum}")
-    return parsed
-
-
-def cli_error(parser: argparse.ArgumentParser, exc: Exception) -> int:
-    """Print one safe CLI error without a traceback."""
-    parser.exit(2, f"{parser.prog}: error: {exc}\n")
-    return 2