@ictechgy/context-guard 0.4.7 → 0.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ictechgy/context-guard",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "ContextGuard CLI helpers for keeping AI coding agent context focused and local-first.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/ictechgy/context-guard#readme",

package/packaging/homebrew/context-guard.rb.template

@@ -5,7 +5,7 @@ class ContextGuard < Formula
 
   desc "Local-first context guardrails for AI coding agents"
   homepage "https://github.com/ictechgy/context-guard"
-  url "https://github.com/ictechgy/context-guard/archive/refs/tags/v0.4.7.tar.gz"
+  url "https://github.com/ictechgy/context-guard/archive/refs/tags/v0.4.8.tar.gz"
   sha256 "REPLACE_WITH_RELEASE_TARBALL_SHA256"
   license "Apache-2.0"
 

package/plugins/context-guard/.claude-plugin/plugin.json

@@ -37,5 +37,5 @@
     "gated-experiments",
     "future-roadmap"
   ],
-  "version": "0.4.7"
+  "version": "0.4.9"
 }

package/plugins/context-guard/README.ko.md

@@ -113,7 +113,7 @@ brief 모드는 코딩 에이전트가 군더더기를 줄이도록 요청하되
 
 ContextGuard는 모델 토큰을 줄이기 위해 작업을 외부 AI 서비스로 전송하지 않습니다. 모든 헬퍼 명령은 로컬에서 동작합니다. 로컬 RAM/디스크 보관본은 다음에 보낼 컨텍스트를 줄이는 데 도움될 수 있지만 provider prompt cache를 대체하지 않습니다. Anthropic 배포나 청구 설명 전에는 공식 prompt caching/pricing 문서를 다시 확인하세요: https://docs.anthropic.com/en/build-with-claude/prompt-caching 및 https://platform.claude.com/docs/en/about-claude/pricing.
 
-미래 learned, self-hosted 최적화 아이디어는 [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md)에 gated experiment로 기록하며, fixture-only 시작 예시는 [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md)에 둡니다. learned compression은 `context-guard experiments plan learned-compression` dry-run checker만 shipped 상태이고, self-hosted metrics ledger는 `context-guard experiments plan self-hosted-metrics-ledger` dry-run preview만, local proxy는 `context-guard experiments plan local-proxy` localhost-only dry-run advisory plan만 shipped 상태이며 no listener/no traffic forwarding/no API-key persistence/read-only ledger boundary를 유지합니다. learned/synthetic compressor runtime·embedding·reranker·model call·replacement 생성, self-hosted KV/latent runtime 최적화, 실제 proxy forwarding runtime은 shipped가 아닙니다. multimodal OCR/crop은 `context-guard experiments plan visual-crop-ocr` dry-run planner만 shipped 상태이고 실제 OCR/crop runtime·스크린샷 캡처·이미지 파싱·외부 OCR/이미지 서비스 호출은 shipped가 아닙니다. 이 radar와 fixture는 provider가 측정한 matched-task 근거 없이 hosted API 절감을 주장하지 않습니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, context-diff compaction, local proxy constraint도 별도 미래 PR이 gate를 통과하기 전까지 experimental/non-shipped로 묶습니다.
+미래 learned, self-hosted 최적화 아이디어는 [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md)에 gated experiment로 기록하며, fixture-only 시작 예시는 [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md)에 둡니다. learned compression은 `context-guard experiments plan learned-compression` dry-run checker와 명시적 `context-guard experiments emit learned-compression` caller-supplied candidate emitter만 shipped 상태이고, self-hosted-metrics-ledger는 dry-run preview와 명시적 `context-guard experiments record self-hosted-metrics-ledger` local JSONL record를 제공하며, dry-run preview는 ledger 파일을 쓰지 않습니다. visual crop/OCR은 caller-supplied evidence-pack emit, context-diff는 verified-receipt caller-supplied replacement emit만 제공합니다. local proxy는 `context-guard experiments plan local-proxy` localhost-only dry-run advisory plan, design-only `context-guard experiments plan local-proxy-external-forwarding` gate, 명시적 `context-guard experiments record local-proxy-runtime-gate --ledger-jsonl ...` gate row record, one-shot `context-guard experiments serve local-proxy` loopback forwarding MVP와 successful forwarded request용 optional shifted-cost diagnostic JSONL row만 shipped 상태입니다. record는 no listener/no traffic forwarding/no DNS lookup/no external service/no API-key persistence boundary를 유지하고, serve는 literal loopback IP·`--once`·credential-free request만 허용하고 CONNECT/TLS proxying도 지원하지 않습니다. `--diagnostic-ledger-jsonl`은 successful forwarded request 뒤에만 진단 row를 쓰며 raw header/body나 hosted-savings evidence를 저장하지 않습니다. `plan local-proxy-external-forwarding`은 threat model, HTTPS allowlist, credential redaction, provider-evidence boundary를 점검하는 dry-run design gate이고 listener, DNS lookup, external service call, traffic forwarding, credential persistence, external proxy forwarding runtime, hosted savings claim을 제공하지 않습니다. learned/synthetic compressor 실행·embedding·reranker·model call·생성형 replacement, generated OCR/crop 또는 visual-token pruning, self-hosted KV/latent runtime 최적화, one-shot literal-loopback local proxy MVP를 넘어선 external/daemon/credential-bearing proxy forwarding runtime은 shipped가 아닙니다. 이 radar와 fixture는 provider가 측정한 matched-task 근거 없이 hosted API 절감을 주장하지 않습니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, generated visual-token reduction, broader local proxy forwarding constraint도 별도 미래 PR이 gate를 통과하기 전까지 experimental/non-shipped로 묶습니다.
 
 교차 에이전트 규칙 스니펫은 권고 사항입니다. 대상 에이전트가 반드시 따른다고 보장할 수 없으므로, 절감 주장이 필요하면 실제 전후 동작을 직접 측정하세요.
 

package/plugins/context-guard/README.md

@@ -119,7 +119,7 @@ These helpers reduce common sources of context bloat, but they do not guarantee
 
 ContextGuard also does not send work to external AI providers to save model tokens. All helper commands run locally. Local RAM/disk receipts can reduce what you choose to send, but they do not replace a provider prompt cache. Before release or billing claims for Anthropic, recheck the official prompt-caching and pricing docs: https://docs.anthropic.com/en/build-with-claude/prompt-caching and https://platform.claude.com/docs/en/about-claude/pricing.
 
-Future learned, multimodal, and self-hosted optimization ideas are tracked in [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md), with fixture-only starters in [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md). ContextGuard ships dry-run planners/checkers for learned compression, self-hosted metrics ledger previews, and local-proxy advisory plans only; learned/synthetic compressor runtime, embeddings, rerankers, model calls, replacement generation, self-hosted KV/latent runtime optimization, and actual proxy forwarding runtime are not shipped. That radar and the fixtures do not claim hosted API savings without provider-measured matched-task evidence. The radar's later-roadmap gates also keep neural/semantic compression, trust-tiered injection-aware compression, context-diff compaction, and local proxy constraints experimental/non-shipped until a separate future PR satisfies those gates.
+Future learned, multimodal, and self-hosted optimization ideas are tracked in [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md), with fixture-only starters in [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md). ContextGuard ships dry-run planners/checkers for local-proxy advisory plans and design-only external-forwarding gates, plus narrow explicit local runtimes for caller-supplied context-diff replacement payloads, caller-supplied visual crop/OCR evidence packs, caller-supplied learned-compression prose candidates, self-hosted metrics JSONL sidecar records, local-proxy runtime-gate JSONL records, one-shot `serve local-proxy` loopback forwarding, and optional shifted-cost diagnostic JSONL rows for successful forwarded requests. Learned/synthetic compressor execution beyond the caller-supplied candidate emitter, embeddings, rerankers, model calls, generated replacement text, screenshot capture, image cropping, OCR execution, image parsing, external OCR/image services, output-file evidence writes, self-hosted KV/latent runtime optimization beyond explicit local metrics recording, and external/daemon/hostname-DNS, credential-bearing, or external proxy forwarding beyond literal-loopback one-request HTTP forwarding are not shipped. That radar and the fixtures do not claim hosted API savings without provider-measured matched-task evidence. The radar's later-roadmap gates also keep neural/semantic compression, trust-tiered injection-aware compression, generated visual-token reduction, and broader local proxy forwarding constraints experimental/non-shipped until a separate future PR satisfies those gates.
 
 ## Experimental opt-ins
 
@@ -129,15 +129,22 @@ Experimental lanes are default off. The registry is project-local metadata only;
 context-guard experiments list
 context-guard experiments status --json
 context-guard experiments plan context-diff-compaction --json < change.diff
+context-guard experiments emit context-diff-compaction --receipt-id <artifact-id> --reexpand-command "context-guard-artifact get <artifact-id> --full" --replacement-file compact-diff.txt --json < change.diff
 context-guard experiments plan visual-crop-ocr --json --full-evidence-receipt <id> --crop-label <label> --crop-bounds 0,0,100,100 --image-size 800,600 --missed-context-note "outside crop omitted"
+context-guard experiments emit visual-crop-ocr --json --full-evidence-receipt <id> --crop-label <label> --crop-bounds 0,0,100,100 --image-size 800,600 --ocr-text "visible text" --ocr-confidence 0.9 --ocr-error-note "glyph may be uncertain" --missed-context-note "outside crop omitted"
 context-guard experiments plan learned-compression --json --sanitized --trusted-source --exact-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" < sanitized-prose.txt
+context-guard experiments emit learned-compression --json --sanitized --trusted-source --exact-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" --replacement-file compact-prose.txt < sanitized-prose.txt
 context-guard experiments plan self-hosted-metrics-ledger --json --latency-ms 123.5 --peak-memory-mb 2048 --quality-score 0.98
+context-guard experiments record self-hosted-metrics-ledger --ledger-jsonl .context-guard/self-hosted-metrics.jsonl --latency-ms 123.5 --peak-memory-mb 2048 --quality-score 0.98 --json
 context-guard experiments plan local-proxy --json --bind-host 127.0.0.1 --target-host 127.0.0.1 --runtime-gate-ack
+context-guard experiments plan local-proxy-external-forwarding --external-forwarding-intent --external-forwarding-design-ack --allow-host api.example.com --allow-scheme https --credential-redaction-policy strip-sensitive-headers --provider-evidence-boundary diagnostic-only-provider-measured-required --threat-model-note "Only user-owned HTTPS endpoint; sensitive headers are stripped before any future forwarding." --json
+context-guard experiments record local-proxy-runtime-gate --ledger-jsonl .context-guard/local-proxy-gates.jsonl --bind-host 127.0.0.1 --target-host 127.0.0.1 --runtime-gate-ack --json
+context-guard experiments serve local-proxy --bind-host 127.0.0.1 --bind-port 18080 --target-host 127.0.0.1 --target-port 18081 --runtime-gate-ack --forwarding-gate-ack --once --diagnostic-ledger-jsonl .context-guard/local-proxy-diagnostics.jsonl --json
 context-guard experiments enable output-receipt-trim --root .
 context-guard experiments disable output-receipt-trim --root .
 ```
 
-Use `--config <path>` only for an explicit project-local override. Registry entries include risk, gate requirements, explicit command/flag surfaces, and claim boundaries; hosted API token/cost savings still require provider-measured matched-task evidence. The registry can discover existing explicit-flag experiments such as `context-guard-trim-output --digest ... --artifact-receipt` and `context-guard-compress --protected-policy`, and it can run dry-run advisory planners such as `context-guard experiments plan context-diff-compaction`, `context-guard experiments plan visual-crop-ocr`, `context-guard experiments plan learned-compression`, `context-guard experiments plan self-hosted-metrics-ledger`, and `context-guard experiments plan local-proxy`. The visual planner is shipped only as a metadata/fixture review surface: OCR/crop runtime, screenshot capture, image parsing, and external OCR/image services are not shipped. The learned-compression checker is likewise a deny-by-default dry-run policy check: learned/synthetic compressor runtime, embeddings, rerankers, model calls, and replacement generation are not shipped. The self-hosted metrics planner emits a read-only ledger-compatible preview for explicit local/model-server latency, memory, quality, energy, throughput, and local-cost metrics; it does not write a ledger or permit hosted API token/cost savings claims. The local-proxy planner emits localhost-only advisory metadata only: it starts no listener, forwards no traffic, persists no API keys, writes no ledger, blocks non-local targets, and requires a separate future runtime gate before any forwarding implementation. `experiments enable` records intent only; it does not run those helpers, remove the need for their explicit flags, or permit replacing content without exact receipt/re-expand evidence.
+Use `--config <path>` only for an explicit project-local override. Registry entries include risk, gate requirements, explicit command/flag surfaces, and claim boundaries; hosted API token/cost savings still require provider-measured matched-task evidence. The registry can discover existing explicit-flag experiments such as `context-guard-trim-output --digest ... --artifact-receipt` and `context-guard-compress --protected-policy`, run dry-run advisory planners such as `context-guard experiments plan context-diff-compaction`, `context-guard experiments plan visual-crop-ocr`, `context-guard experiments plan learned-compression`, `context-guard experiments plan self-hosted-metrics-ledger`, `context-guard experiments plan local-proxy`, and design-only `context-guard experiments plan local-proxy-external-forwarding`, and run explicit local runtimes such as `context-guard experiments emit context-diff-compaction ...`, `context-guard experiments emit visual-crop-ocr ...`, `context-guard experiments emit learned-compression ...`, `context-guard experiments record self-hosted-metrics-ledger ...`, `context-guard experiments record local-proxy-runtime-gate ...`, `context-guard experiments serve local-proxy ...`, and successful-forward `context-guard experiments serve local-proxy --diagnostic-ledger-jsonl ...` diagnostics. The context-diff emit runtime only emits caller-supplied compact replacements when reviewable hunks, exact local artifact re-expand metadata whose stored content matches the input diff, and a smaller replacement are present; it does not generate semantic compression or permit hosted savings claims. The visual lane ships a dry-run planner plus an explicit local evidence-pack emitter: both use only caller-supplied full-evidence receipts, crop metadata, OCR text, confidence/error notes, and missed-context notes; screenshot capture, image cropping, OCR execution, image parsing, external OCR/image services, output-file writes, and hosted savings claims are not shipped. The learned-compression lane ships a deny-by-default dry-run policy check plus an explicit local candidate emitter for caller-supplied compact prose with verified exact fallback content: learned/synthetic compressor execution, embeddings, rerankers, model calls, subprocesses, external services, generated replacement text, and hosted savings claims are not shipped. The self-hosted metrics planner emits a dry-run ledger-compatible preview for explicit local/model-server latency, memory, quality, energy, throughput, and local-cost metrics; the dry-run preview does not write a ledger, while `context-guard experiments record self-hosted-metrics-ledger --ledger-jsonl ...` writes only local JSONL sidecars and still does not permit hosted API token/cost savings claims. The local-proxy planner emits localhost-only advisory metadata only, while `context-guard experiments record local-proxy-runtime-gate --ledger-jsonl ...` appends one local gate row only after localhost-only metadata and `--runtime-gate-ack`: it starts no listener, forwards no traffic, and performs no DNS lookup. `context-guard experiments serve local-proxy ...` is the separate forwarding MVP: it requires `--forwarding-gate-ack --once`, literal loopback bind/target IPs, no hostname DNS targets, nonzero ports, byte/time limits, and credential-free requests; it performs no external forwarding, no CONNECT/TLS proxying, no API-key persistence, and no hosted-savings claim. `--diagnostic-ledger-jsonl` writes one shifted-cost diagnostic row only after a successful forwarded request, with no raw headers/bodies and no hosted-savings evidence. `plan local-proxy-external-forwarding` emits threat-model/allowlist/redaction/provider-evidence design metadata only and still starts no listener, performs no DNS lookup, calls no external service, forwards no traffic, persists no credentials, and does not ship an external proxy forwarding runtime. `experiments enable` records intent only; it does not run those helpers, remove the need for their explicit flags, or permit replacing content without exact receipt/re-expand evidence.
 
 Cross-agent rule snippets are advisory: the target agent may ignore them, so measure actual before/after behavior when you need a savings claim.
 

package/plugins/context-guard/bin/context-guard

@@ -11,11 +11,17 @@ import json
 import os
 from pathlib import Path
 import subprocess
+import stat
 import sys
 from typing import NoReturn
 
 COMMAND_NAME = "context-guard"
 PACKAGE_NAME = "@ictechgy/context-guard"
+MAX_VERSION_METADATA_BYTES = 64 * 1024
+ALLOWED_FIRST_ABSOLUTE_SYMLINKS = {
+    "tmp": Path("/private/tmp"),
+    "var": Path("/private/var"),
+}
 
 HELPER_SUBCOMMANDS: dict[str, tuple[str, ...]] = {
     "setup": ("context-guard-setup",),
@@ -50,16 +56,182 @@ def _script_dir() -> Path:
 
 def _candidate_roots() -> list[Path]:
     script_dir = _script_dir()
-    roots = [script_dir.parent, script_dir.parent.parent, Path.cwd()]
+    roots = [script_dir.parent, script_dir.parent.parent]
     # When run from context-guard-kit in a checkout, the repo root is one level up.
     if script_dir.name == "context-guard-kit":
         roots.insert(0, script_dir.parent)
     return list(dict.fromkeys(roots))
 
 
+def _normalized_link_target(anchor: Path, raw_target: str) -> Path:
+    target = Path(raw_target)
+    if target.is_absolute():
+        return Path(os.path.normpath(str(target)))
+    return Path(os.path.normpath(str(anchor / target)))
+
+
+def _normalize_allowed_first_absolute_symlink(path: Path) -> Path:
+    if not path.is_absolute():
+        return path
+    parts = path.parts
+    if len(parts) < 2:
+        return path
+    expected = ALLOWED_FIRST_ABSOLUTE_SYMLINKS.get(parts[1])
+    if expected is None:
+        return path
+    first = Path(path.anchor) / parts[1]
+    try:
+        if first.is_symlink() and _normalized_link_target(Path(path.anchor), os.readlink(first)) == expected:
+            return expected.joinpath(*parts[2:])
+    except OSError:
+        return path
+    return path
+
+
+def _metadata_no_follow_supported() -> bool:
+    return (
+        hasattr(os, "O_NOFOLLOW")
+        and os.open in getattr(os, "supports_dir_fd", set())
+        and os.stat in getattr(os, "supports_dir_fd", set())
+        and os.stat in getattr(os, "supports_follow_symlinks", set())
+    )
+
+
+def _directory_open_flags(*, follow_final: bool = False) -> int:
+    flags = os.O_RDONLY
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_DIRECTORY"):
+        flags |= os.O_DIRECTORY
+    if not follow_final:
+        flags |= os.O_NOFOLLOW
+    return flags
+
+
+def _metadata_file_open_flags() -> int:
+    flags = os.O_RDONLY | os.O_NOFOLLOW
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_NONBLOCK"):
+        flags |= os.O_NONBLOCK
+    if hasattr(os, "O_NOCTTY"):
+        flags |= os.O_NOCTTY
+    return flags
+
+
+def _leaf_name(path: Path) -> str | None:
+    name = path.name
+    if name in {"", ".", ".."}:
+        return None
+    return name
+
+
+def _open_metadata_parent_no_follow(path: Path) -> int | None:
+    if not _metadata_no_follow_supported():
+        return None
+    path = _normalize_allowed_first_absolute_symlink(path)
+    try:
+        if path.is_absolute():
+            current_fd = os.open(path.anchor or os.sep, _directory_open_flags(follow_final=True))
+            parts = path.parts[1:-1]
+        else:
+            current_fd = os.open(".", _directory_open_flags(follow_final=True))
+            parts = path.parts[:-1]
+    except OSError:
+        return None
+    try:
+        for part in parts:
+            if part in {"", "."}:
+                continue
+            if part == "..":
+                return None
+            next_fd = -1
+            try:
+                next_fd = os.open(part, _directory_open_flags(), dir_fd=current_fd)
+                if not stat.S_ISDIR(os.fstat(next_fd).st_mode):
+                    try:
+                        os.close(next_fd)
+                    except OSError:
+                        pass
+                    next_fd = -1
+                    return None
+            except OSError:
+                if next_fd >= 0:
+                    try:
+                        os.close(next_fd)
+                    except OSError:
+                        pass
+                try:
+                    os.close(current_fd)
+                except OSError:
+                    pass
+                current_fd = -1
+                return None
+            try:
+                os.close(current_fd)
+            except OSError:
+                pass
+            current_fd = next_fd
+        owned_fd = current_fd
+        current_fd = -1
+        return owned_fd
+    finally:
+        if current_fd >= 0:
+            try:
+                os.close(current_fd)
+            except OSError:
+                pass
+
+
+def _read_metadata_text(path: Path) -> str | None:
+    path = _normalize_allowed_first_absolute_symlink(path)
+    parent_fd = _open_metadata_parent_no_follow(path)
+    if parent_fd is None:
+        return None
+    fd = -1
+    data = b""
+    try:
+        leaf = _leaf_name(path)
+        if leaf is None:
+            return None
+        pre_open = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
+        if not stat.S_ISREG(pre_open.st_mode):
+            return None
+        if pre_open.st_size > MAX_VERSION_METADATA_BYTES:
+            return None
+        fd = os.open(leaf, _metadata_file_open_flags(), dir_fd=parent_fd)
+        opened = os.fstat(fd)
+        if not stat.S_ISREG(opened.st_mode):
+            return None
+        if opened.st_size > MAX_VERSION_METADATA_BYTES:
+            return None
+        data = os.read(fd, MAX_VERSION_METADATA_BYTES + 1)
+    except OSError:
+        return None
+    finally:
+        if fd >= 0:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        try:
+            os.close(parent_fd)
+        except OSError:
+            pass
+    if len(data) > MAX_VERSION_METADATA_BYTES:
+        return None
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+
+
 def _load_json(path: Path) -> dict[str, object] | None:
+    text = _read_metadata_text(path)
+    if text is None:
+        return None
     try:
-        data = json.loads(path.read_text(encoding="utf-8"))
+        data = json.loads(text)
     except (OSError, json.JSONDecodeError):
         return None
     return data if isinstance(data, dict) else None

package/plugins/context-guard/bin/context-guard-cost

@@ -11,6 +11,7 @@ from __future__ import annotations
 import argparse
 import base64
 import binascii
+import errno
 try:
     import fcntl
 except ImportError:  # pragma: no cover - fcntl is unavailable on Windows.
@@ -49,6 +50,8 @@ DEFAULT_SAFETY_FACTOR = 1.25
 DEFAULT_LARGE_SECTION_BYTES = 64_000
 MAX_LEDGER_ROWS = 20_000
 LEDGER_TAIL_INITIAL_BYTES = 64 * 1024
+LEDGER_OPEN_RETRY_ATTEMPTS = 5
+LEDGER_OPEN_RETRY_SECONDS = 0.01
 TTL_SECONDS = {"5m": 5 * 60, "1h": 60 * 60}
 ANTHROPIC_DOCS_URL = "https://docs.anthropic.com/en/build-with-claude/prompt-caching"
 ANTHROPIC_PRICING_URL = "https://platform.claude.com/docs/en/about-claude/pricing"
@@ -58,6 +61,10 @@ ALLOWED_FIRST_COMPONENT_SYMLINKS = {
 }
 DIR_FD_OPEN_SUPPORTED = os.open in getattr(os, "supports_dir_fd", set())
 NO_FOLLOW_SUPPORTED = hasattr(os, "O_NOFOLLOW")
+DIR_FD_STAT_NOFOLLOW_SUPPORTED = (
+    os.stat in getattr(os, "supports_dir_fd", set())
+    and os.stat in getattr(os, "supports_follow_symlinks", set())
+)
 
 SECRET_RE = re.compile(
     r"(?is)("
@@ -148,25 +155,68 @@ def token_proxy_obj(data: Any) -> int:
     return token_proxy_text(json_bytes(data))
 
 
+def read_bounded_regular_path(path: str | Path, *, max_bytes: int, label: str) -> tuple[str, bool]:
+    if max_bytes < 1 or max_bytes > MAX_MAX_BYTES:
+        fail(f"max bytes must be between 1 and {MAX_MAX_BYTES}")
+    p = reject_symlink_components(Path(path), label=label)
+    leaf_name = _private_leaf_name(p, label=label)
+    parent_fd = -1
+    fd = -1
+    try:
+        parent_fd = open_directory_no_follow(p.parent, label=f"{label} parent")
+        if not DIR_FD_STAT_NOFOLLOW_SUPPORTED:
+            fail(f"{label} requires dir_fd stat support for symlink-safe regular-file validation")
+        try:
+            pre_st = os.stat(leaf_name, dir_fd=parent_fd, follow_symlinks=False)
+        except OSError as exc:
+            fail(f"could not inspect {label}: {os_error_detail(exc)}")
+        if not stat.S_ISREG(pre_st.st_mode):
+            fail(f"{label} must be a regular file")
+        flags = _base_open_flags() | _no_follow_flag(label=label)
+        if hasattr(os, "O_NONBLOCK"):
+            flags |= os.O_NONBLOCK
+        if hasattr(os, "O_NOCTTY"):
+            flags |= os.O_NOCTTY
+        fd = os.open(leaf_name, flags, dir_fd=parent_fd)
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            fail(f"{label} must be a regular file")
+        chunks: list[bytes] = []
+        remaining = max_bytes + 1
+        while remaining > 0:
+            chunk = os.read(fd, min(64 * 1024, remaining))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        raw = b"".join(chunks)
+    except CostGuardError:
+        raise
+    except OSError as exc:
+        fail(f"could not read {label}: {os_error_detail(exc)}")
+    finally:
+        if fd >= 0:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        if parent_fd >= 0:
+            try:
+                os.close(parent_fd)
+            except OSError:
+                pass
+    truncated = len(raw) > max_bytes
+    if truncated:
+        raw = raw[:max_bytes]
+    return raw.decode("utf-8", errors="replace"), truncated
+
+
 def read_text_path(path: str, *, max_bytes: int = DEFAULT_MAX_BYTES) -> tuple[str, bool]:
     if max_bytes < 1 or max_bytes > MAX_MAX_BYTES:
         fail(f"max bytes must be between 1 and {MAX_MAX_BYTES}")
     if path == "-":
         raw = sys.stdin.buffer.read(max_bytes + 1)
     else:
-        p = Path(path)
-        try:
-            st = p.stat()
-        except OSError as exc:
-            fail(f"could not read input file: {exc}")
-        if not stat.S_ISREG(st.st_mode):
-            fail("input path must be a regular file")
-        if st.st_size > max_bytes + 1:
-            # Read only the bounded prefix so large requests cannot exhaust memory.
-            with p.open("rb") as fh:
-                raw = fh.read(max_bytes + 1)
-        else:
-            raw = p.read_bytes()
+        return read_bounded_regular_path(path, max_bytes=max_bytes, label="input file")
     truncated = len(raw) > max_bytes
     if truncated:
         raw = raw[:max_bytes]
@@ -494,20 +544,20 @@ def _base_open_flags() -> int:
     return flags
 
 
-def _no_follow_flag() -> int:
+def _no_follow_flag(*, label: str = "private local cost storage") -> int:
     if not NO_FOLLOW_SUPPORTED:
-        fail("private local cost storage requires O_NOFOLLOW support")
+        fail(f"{label} requires O_NOFOLLOW support")
     return os.O_NOFOLLOW
 
 
-def _directory_open_flags(*, follow_final: bool = False) -> int:
+def _directory_open_flags(*, follow_final: bool = False, label: str = "private local cost storage") -> int:
     flags = os.O_RDONLY
     if hasattr(os, "O_CLOEXEC"):
         flags |= os.O_CLOEXEC
     if hasattr(os, "O_DIRECTORY"):
         flags |= os.O_DIRECTORY
     if not follow_final:
-        flags |= _no_follow_flag()
+        flags |= _no_follow_flag(label=label)
     return flags
 
 
@@ -572,18 +622,18 @@ def reject_symlink_components(path: Path, *, label: str) -> Path:
     return path
 
 
-def open_private_directory(path: Path, *, label: str) -> int:
+def open_directory_no_follow(path: Path, *, label: str) -> int:
     """Open an existing directory without following symlink path components."""
 
     if not dir_fd_open_supported():
-        fail(f"{label} requires dir_fd support for symlink-safe private storage")
+        fail(f"{label} requires dir_fd support for symlink-safe directory traversal")
     path = reject_symlink_components(path, label=label)
-    flags = _directory_open_flags()
+    flags = _directory_open_flags(label=label)
     if path.is_absolute():
         anchor = path.anchor or os.sep
         parts = path.parts[1:]
         try:
-            current_fd = os.open(anchor, _directory_open_flags(follow_final=True))
+            current_fd = os.open(anchor, _directory_open_flags(follow_final=True, label=label))
         except OSError as exc:
             fail(f"could not inspect {label}: {os_error_detail(exc)}")
     else:
@@ -635,6 +685,12 @@ def open_private_directory(path: Path, *, label: str) -> int:
                 pass
 
 
+def open_private_directory(path: Path, *, label: str) -> int:
+    """Open an existing private-storage directory without following symlinks."""
+
+    return open_directory_no_follow(path, label=label)
+
+
 def fsync_directory_fd(fd: int) -> None:
     if os.name != "posix":
         return
@@ -676,7 +732,7 @@ def open_private_regular_fd_for_read(path: Path, *, label: str) -> int:
     fd = -1
     try:
         parent_fd = open_private_directory(path.parent, label=f"{label} parent")
-        fd = os.open(leaf_name, _base_open_flags() | _no_follow_flag(), dir_fd=parent_fd)
+        fd = os.open(leaf_name, _base_open_flags() | _no_follow_flag(label=label), dir_fd=parent_fd)
         st = os.fstat(fd)
         if not stat.S_ISREG(st.st_mode):
             fail(f"{label} must be a regular file")
@@ -1138,41 +1194,47 @@ def open_private_regular_file_for_append(path: Path, *, label: str) -> int:
     flags = os.O_WRONLY | os.O_CREAT | os.O_APPEND | _no_follow_flag()
     if hasattr(os, "O_CLOEXEC"):
         flags |= os.O_CLOEXEC
-    parent_fd = -1
-    fd = -1
-    try:
-        parent_fd = open_private_directory(path.parent, label=f"{label} parent")
-        fd = os.open(leaf_name, flags, 0o600, dir_fd=parent_fd)
-        st = os.fstat(fd)
-        if not stat.S_ISREG(st.st_mode):
-            fail(f"{label} must be a regular file")
-        try:
-            os.fchmod(fd, 0o600)
-        except (AttributeError, OSError):
-            pass
-        st = os.fstat(fd)
-        if os.name == "posix" and stat.S_IMODE(st.st_mode) != 0o600:
-            fail(f"could not verify {label} privacy: expected mode 0600")
-        owned_fd = fd
+    for attempt in range(LEDGER_OPEN_RETRY_ATTEMPTS):
+        parent_fd = -1
         fd = -1
-        return owned_fd
-    except CostGuardError:
-        raise
-    except OSError as exc:
-        fail(f"could not open {label}: {os_error_detail(exc)}")
-    finally:
-        if fd >= 0:
-            # Ownership transfers to the caller only on the successful return
-            # above. On errors, close before surfacing a deterministic message.
-            try:
-                os.close(fd)
-            except OSError:
-                pass
-        if parent_fd >= 0:
+        try:
+            parent_fd = open_private_directory(path.parent, label=f"{label} parent")
+            fd = os.open(leaf_name, flags, 0o600, dir_fd=parent_fd)
+            st = os.fstat(fd)
+            if not stat.S_ISREG(st.st_mode):
+                fail(f"{label} must be a regular file")
             try:
-                os.close(parent_fd)
-            except OSError:
+                os.fchmod(fd, 0o600)
+            except (AttributeError, OSError):
                 pass
+            st = os.fstat(fd)
+            if os.name == "posix" and stat.S_IMODE(st.st_mode) != 0o600:
+                fail(f"could not verify {label} privacy: expected mode 0600")
+            owned_fd = fd
+            fd = -1
+            return owned_fd
+        except CostGuardError:
+            raise
+        except OSError as exc:
+            if exc.errno == errno.ENOENT and attempt + 1 < LEDGER_OPEN_RETRY_ATTEMPTS:
+                time.sleep(LEDGER_OPEN_RETRY_SECONDS)
+                continue
+            fail(f"could not open {label}: {os_error_detail(exc)}")
+        finally:
+            if fd >= 0:
+                # Ownership transfers to the caller only on the successful
+                # return above. On errors, close before surfacing a
+                # deterministic message.
+                try:
+                    os.close(fd)
+                except OSError:
+                    pass
+            if parent_fd >= 0:
+                try:
+                    os.close(parent_fd)
+                except OSError:
+                    pass
+    raise AssertionError("unreachable: append retry loop exits via return or fail")
 
 
 def load_ledger(store_dir: Path) -> list[dict[str, Any]]:
@@ -1280,7 +1342,7 @@ def default_pricing_profile() -> dict[str, Any]:
     }
 
 
-def load_pricing_profile(raw: str | None) -> dict[str, Any]:
+def load_pricing_profile(raw: str | None, *, max_bytes: int = DEFAULT_MAX_BYTES) -> dict[str, Any]:
     profile = default_pricing_profile()
     if not raw:
         return profile
@@ -1288,7 +1350,12 @@ def load_pricing_profile(raw: str | None) -> dict[str, Any]:
         if raw.lstrip().startswith("{"):
             override = json.loads(raw, parse_constant=reject_json_constant)
         else:
-            override = json.loads(Path(raw).read_text(encoding="utf-8"), parse_constant=reject_json_constant)
+            text, truncated = read_bounded_regular_path(raw, max_bytes=max_bytes, label="pricing profile")
+            if truncated:
+                fail("pricing profile exceeded max bytes")
+            override = json.loads(text, parse_constant=reject_json_constant)
+    except CostGuardError:
+        raise
     except (OSError, json.JSONDecodeError, ValueError) as exc:
         fail(f"could not load pricing profile: {exc}")
     if not isinstance(override, dict):
@@ -1542,7 +1609,7 @@ def annotate_cache_state(
 def preflight_command(args: argparse.Namespace) -> int:
     request_raw, _truncated = load_json_input(args.request, max_bytes=args.max_bytes)
     request = require_json_object(request_raw, "request")
-    profile = load_pricing_profile(args.pricing_profile)
+    profile = load_pricing_profile(args.pricing_profile, max_bytes=args.max_bytes)
     if args.usd_to_krw is not None:
         profile["usd_to_krw"] = usd_to_krw(profile, args.usd_to_krw)
     if args.budget_usd is not None:
@@ -1809,7 +1876,7 @@ def observe_command(args: argparse.Namespace) -> int:
         usage = usage_raw
     if not isinstance(usage, dict):
         fail("usage must be a JSON object or an object containing a usage object")
-    profile = load_pricing_profile(args.pricing_profile)
+    profile = load_pricing_profile(args.pricing_profile, max_bytes=args.max_bytes)
     if args.usd_to_krw is not None:
         profile["usd_to_krw"] = usd_to_krw(profile, args.usd_to_krw)
     model = str(args.model or (usage_raw.get("model") if isinstance(usage_raw, dict) else "") or "unknown")
@@ -2217,7 +2284,7 @@ def emit(data: dict[str, Any], *, json_mode: bool) -> None:
 def add_common_cost_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--pricing-profile", help="JSON string or file with input/output rates, cache multipliers, and usd_to_krw")
     parser.add_argument("--usd-to-krw", type=float, help="override USD→KRW exchange rate used for estimates")
-    parser.add_argument("--max-bytes", type=int, default=DEFAULT_MAX_BYTES, help=f"maximum JSON input bytes (default: {DEFAULT_MAX_BYTES})")
+    parser.add_argument("--max-bytes", type=int, default=DEFAULT_MAX_BYTES, help=f"maximum JSON input and pricing profile file bytes (default: {DEFAULT_MAX_BYTES})")
     parser.add_argument("--json", action="store_true", help="emit machine-readable JSON")