context-loader 1.3.2__tar.gz → 1.3.3__tar.gz

{context_loader-1.3.2 → context_loader-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: context-loader
-Version: 1.3.2
+Version: 1.3.3
 Summary: Render deterministic local Git context for any executor
 License:                                  Apache License
                                     Version 2.0, January 2004
@@ -219,14 +219,14 @@ Python standard library.
 
 ## Open-source quick start
 
-Current stable release: **1.3.2**. Local CLI for coding-agent workflows; renders deterministic Markdown or JSON.
+Current stable release: **1.3.3**. Local CLI for coding-agent workflows; renders deterministic Markdown or JSON.
 
 ```bash
-uv tool install 'context-loader==1.3.2'
+uv tool install 'context-loader==1.3.3'
 ```
 
 ```bash
-pip install 'context-loader==1.3.2'
+pip install 'context-loader==1.3.3'
 ```
 
 ```bash
@@ -239,21 +239,21 @@ project-context --repo /path/to/repo --format json
 
 ## Install
 
-Source version: `1.3.2`. Install its matching published release or an exact source commit.
+Source version: `1.3.3`. Install its matching published release or an exact source commit.
 
 Install via `uv`:
 
 ```bash
-uv tool install 'context-loader==1.3.2'
+uv tool install 'context-loader==1.3.3'
 ```
 
 Install via `pip`:
 
 ```bash
-pip install 'context-loader==1.3.2'
+pip install 'context-loader==1.3.3'
 ```
 
-For development or source-based installs tracking current repository (`1.3.2`):
+For development or source-based installs tracking current repository (`1.3.3`):
 
 ```bash
 uv tool install git+https://github.com/xuanheng-tech/context-loader.git
@@ -350,7 +350,7 @@ set differs, as described under “Compact model consumption”. The declared co
   "schema_version": 3,
   "tool": {
     "name": "context-loader",
-    "version": "1.3.2"
+    "version": "1.3.3"
   },
   "repository": {
     "requested_path": "/canonical/requested/path",
@@ -397,7 +397,14 @@ context, in assembly order, after the existing newline normalization and truncat
 distinguishes `repository` from `global`; version 1.0.0's fixed root-file selection currently emits
 only `repository` sources and does not add any global-file discovery.
 
-`statuses` lists machine-readable collection and render conditions that previously appeared only inside `context` Markdown — plus the nested-context truncation flags, which exist only in machine form: skipped or absent sources, truncated sources, unreadable directory-tree entries, directory-tree entries whose directory holds more entries than one enumeration examines, sections omitted under the global output budget, truncated working-tree, declared-command or directory-tree listings, and truncated nested-`AGENTS.md` presence reports. A skipped or absent source reports the code of the condition the collector observed (`not_present`, `skipped_symlink`, `skipped_not_regular`, `skipped_encoding`, `skipped_unreadable`); the sentence in `context` is rendered from that same condition, so wording and code cannot drift apart. Each entry has stable `code`, `subject_kind`, and `subject` fields. The two `nested_agents_*` codes mirror the `nested_context` truncation booleans for consumers that branch only on `statuses`; the full `nested_context` object remains a first-class field, never folded into `statuses`. Callers can ignore `statuses` safely.
+`statuses` lists skipped or absent sources, truncated sources, unreadable tree entries,
+directories whose listing exceeds its retention cap, globally omitted sections, and truncated
+working-tree, command, tree or nested-`AGENTS.md` listings. A skipped or absent source reports
+the observed condition (`not_present`, `skipped_symlink`, `skipped_not_regular`,
+`skipped_encoding`, `skipped_unreadable`); its sentence in `context` comes from that same
+condition. Each entry has stable `code`, `subject_kind`, and `subject` fields. The two
+`nested_agents_*` codes mirror the `nested_context` truncation booleans; the complete object
+remains a separate field. Callers can ignore `statuses` safely.
 
 The optional `selection` object is present only on a rendered `AGENTS.md` source. Its section entries
 contain heading, heading level, and fixed selection reasons; it never contains the original focus or
@@ -417,7 +424,7 @@ separator, with the array's brackets charged to the first entry — so the emitt
 more than the budget it declares. Because quoting is counted, an array already near the cap can
 report one path fewer than an older release did, and then says so through `list_truncated`.
 `scan_truncated` means the depth (4) or directory-count (2,000) budget was reached, a directory
-held more entries than one enumeration examines (1,024), or a directory or entry could not be
+held more entries than one listing retains (1,024), or a directory or entry could not be
 read, so absence of a path is not proof of absence of the file. Nested paths
 are sanitized with the same escaping the Markdown uses for repository-derived text, so a nested name
 the filesystem could not decode never breaks the document;
@@ -426,6 +433,16 @@ see “Limits” for the root paths that are emitted verbatim. The corresponding
 Presence is not instruction: whether a nested file applies, and its text, remain the caller's
 judgment; Markdown output is unchanged.
 
+Escaped names remain reversible and distinct: a literal backslash becomes `\\`, a backtick
+becomes `\x60`, ASCII controls and undecodable filesystem bytes become `\xNN`, and other
+non-printable Unicode characters become `\uNNNN` or `\UNNNNNNNN`. Printable Unicode stays
+unchanged. After JSON decoding, recover POSIX path bytes by reading escapes from left to right:
+`\\` yields one backslash byte, `\xNN` yields that byte, and Unicode escapes and ordinary
+characters yield their UTF-8 bytes. Thus a backtick, a literal `\x60`, an undecodable byte
+`0x80`, and Unicode `U+0080` all have different representations. This applies to nested paths
+and displayed tree/change/status names; the verbatim root/source paths retain their existing
+semantics.
+
 ### Compact model consumption (`--format json-compact`)
 
 `--format json-compact` emits a `schema_version` 4 document: exactly the version-3 document with
@@ -453,7 +470,7 @@ although 1.1.0 added the top-level `statuses` key. From release 1.2.0 onward eac
 names exactly one key set, and a new number is issued whenever a key set would otherwise be reused.
 
 The JSON schema version and package version are independent: this build emits `schema_version` `3`
-for `--format json` and `4` for `--format json-compact`, while `tool.version` is `1.3.2`. Version 1
+for `--format json` and `4` for `--format json-compact`, while `tool.version` is `1.3.3`. Version 1
 and 2 are the exact shapes already published in release 1.2.0 and are never reused: because
 `nested_context` changes the default document's key set, version 3 names the current full-document
 key set and version 4 names the compact projection.
@@ -527,10 +544,11 @@ bullet is a per-component, read or capture bound, as each one states:
   16 KiB, including a 4-KiB maximum small head
 - `README.md`: 16 KiB
 - Each entry file: 8 KiB
-- All entry-file bodies: 24 KiB
+- All entry-file bodies: 24 KiB, including truncation markers. Room is reserved for markers
+  on later text sources, so exhausting the budget never hides that their bodies were cut.
 - Declared commands: 8 KiB
 - Directory tree: 12 KiB of listing body, 300 entries, and depth 2. Each directory is
-  enumerated up to 512 entries, keeping the alphabetically first names so the listing never
+  retains and classifies up to 512 entries, keeping the alphabetically first names so the listing never
   depends on operating system order. A directory that holds more is reported by a single
   `Listing incomplete:` line stating the total, the limit and up to three names, and by at most
   eight `directory_listing_incomplete` status entries naming individual directories plus one
@@ -541,8 +559,10 @@ bullet is a per-component, read or capture bound, as each one states:
   alphabetical prefix and the entry budget kept it, so capped siblings displaced by the budget are
   disclosed as their parent's truncation rather than as separate numbers.
   Three limits act in sequence and a name survives only if all three leave room. The 512-entry
-  enumeration limit decides which names a directory offers at all; above it only an alphabetical
-  prefix is ever seen. The 300-entry item budget is then shared between a directory's
+  retention limit decides which names a directory offers at all; above it only an alphabetical
+  prefix is classified. All names must still be scanned to find that prefix, subject to the
+  separate hard name-scan bound below; the retention cap bounds memory and classification work.
+  The 300-entry item budget is then shared between a directory's
   subdirectories and its non-directories: each may take up to half of what remains before the other
   claims the surplus, which stops alphabetically-earlier directories from evicting every file, but
   it is a share rather than a floor -- with a single slot left the non-directories take it. The 12
@@ -561,8 +581,14 @@ bullet is a per-component, read or capture bound, as each one states:
   fence say so. The heading and the code-fence lines are not metered, so the whole Markdown
   section can exceed 12 KiB by that fixed few dozen bytes.
 - Nested `AGENTS.md` presence scan: depth 4, 2,000 directories, at most 32 reported paths, a
-  4 KiB budget metered on the emitted array, and at most 1,024 entries examined per directory;
-  file contents are never read
+  4 KiB budget metered on the emitted array, and at most 1,024 entries retained and classified
+  per directory. Names are scanned to select that prefix, subject to the separate hard
+  name-scan bound below; file contents are never read
+- Directory name scans stop on the first entry beyond 65,536 names per directory. An
+  over-limit directory's entire partial prefix is discarded to keep results independent of
+  operating system order. The tree emits `Skipped: directory name scan limit reached.` and
+  a `directory_scan_limit_exceeded` status; the nested presence scan sets `scan_truncated`.
+  This bounds name iteration, not elapsed time on a blocked filesystem call.
 - Working-tree changes: 100 paths and 4 KiB
 - Recent commits: 8
 - JSON-only listings have no byte budget of their own: `statuses` subjects are escaped names bounded
@@ -570,6 +596,7 @@ bullet is a per-component, read or capture bound, as each one states:
   repository root the filesystem could not decode makes the machine formats exit 1 where Markdown
   still renders
 - Git subprocess output: 16 MiB (bounded while reading)
+- Git status preflight: at most 128 repositories, including initialized nested submodules
 - Candidate file validation: 16 MiB hard read bound
 
 Truncation occurs only at complete UTF-8 and line boundaries and is marked explicitly.
@@ -593,6 +620,13 @@ the remote.
   this is normal after cloning an empty remote.
 - `Ahead / behind: not available` means the commit relationship cannot currently be computed.
   Counts are reported only when the configured upstream commit is available locally.
+- Executable Git clean/process filters can run during `status`, even with optional locks
+  disabled. Before reading status, the loader checks effective repository configuration,
+  including includes, worktree configuration and initialized nested submodules. A non-empty
+  clean/process command causes a safe error with no stdout, even if no current attribute uses
+  it. Disabling a driver silently would change cleanliness semantics. Filter-dependent repositories
+  (including locally configured Git LFS drivers) therefore need ordinary Git inspection outside
+  this loader. Git protocols are also disabled to prevent lazy object retrieval.
 
 ## Exit Codes
 
@@ -605,7 +639,7 @@ or candidate-file content.
 
 ## Not Included
 
-Version 1.3.2 does not provide AI summaries, project-type detection, loading or transport of
+Version 1.3.3 does not provide AI summaries, project-type detection, loading or transport of
 nested `AGENTS.md` contents (the JSON `nested_context` field reports bounded existence only),
 Memory retrieval, semantic ranking, ignore-rule parsing, plugins, profiles, caches, databases,
 network services, MCP, daemons, GUIs, CI/CD, telemetry, or automatic updates.
@@ -618,6 +652,17 @@ Run the complete local check:
 just check
 ```
 
+The lockfile uses public PyPI artifact URLs; no organization mirror or local Renovate preset
+is needed. Renovate keeps scheduled, rate-limited updates and manual merges using a public
+recommended preset plus the repository's explicit settings. Python 3.12 remains the tested
+runtime; widening that range requires testing those interpreters first.
+
+Git test fixtures discard inherited `GIT_*` routing/configuration before creating repositories.
+Permission-sensitive tests must run as a non-root user. Gitea uses `just ci-check`: non-root
+runners execute directly; root containers use `runuser` with an existing account named by
+`CONTEXT_LOADER_CI_USER` (default `ubuntu`). That account must be able to execute the installed
+`uv`, Python and `just`. No `sudo` dependency is required for this CI step.
+
 ## Version maintenance
 
 The versions in `pyproject.toml` and `context_loader/__init__.py`, the `tool_version` in
@@ -638,6 +683,11 @@ only verifies the public release, mirrors its exact formal tag object if missing
 the Gitea Release record. It builds no package and has no PyPI publishing credentials.
 No private endpoint or credential is needed on GitHub.
 
+For environments that permit direct public reads but share an exhausted proxy quota,
+set the Gitea Actions repository variable `RELEASE_PUBLIC_API_DIRECT=true`. The record
+step appends only public GitHub API/PyPI hosts to the existing proxy bypass lists. Without
+this explicit option, the workflow uses its inherited proxy settings.
+
 Release checks use Python 3.12, Git, and the runner's existing OpenSSL CLI. They compare downloaded
 PyPI file bytes, metadata and SHA-256, plus the publisher/tag/commit claims in PyPI's HTTPS-served
 provenance. This is an identity check, not an independent cryptographic Sigstore verifier.

{context_loader-1.3.2 → context_loader-1.3.3}/README.md

@@ -8,14 +8,14 @@ Python standard library.
 
 ## Open-source quick start
 
-Current stable release: **1.3.2**. Local CLI for coding-agent workflows; renders deterministic Markdown or JSON.
+Current stable release: **1.3.3**. Local CLI for coding-agent workflows; renders deterministic Markdown or JSON.
 
 ```bash
-uv tool install 'context-loader==1.3.2'
+uv tool install 'context-loader==1.3.3'
 ```
 
 ```bash
-pip install 'context-loader==1.3.2'
+pip install 'context-loader==1.3.3'
 ```
 
 ```bash
@@ -28,21 +28,21 @@ project-context --repo /path/to/repo --format json
 
 ## Install
 
-Source version: `1.3.2`. Install its matching published release or an exact source commit.
+Source version: `1.3.3`. Install its matching published release or an exact source commit.
 
 Install via `uv`:
 
 ```bash
-uv tool install 'context-loader==1.3.2'
+uv tool install 'context-loader==1.3.3'
 ```
 
 Install via `pip`:
 
 ```bash
-pip install 'context-loader==1.3.2'
+pip install 'context-loader==1.3.3'
 ```
 
-For development or source-based installs tracking current repository (`1.3.2`):
+For development or source-based installs tracking current repository (`1.3.3`):
 
 ```bash
 uv tool install git+https://github.com/xuanheng-tech/context-loader.git
@@ -139,7 +139,7 @@ set differs, as described under “Compact model consumption”. The declared co
   "schema_version": 3,
   "tool": {
     "name": "context-loader",
-    "version": "1.3.2"
+    "version": "1.3.3"
   },
   "repository": {
     "requested_path": "/canonical/requested/path",
@@ -186,7 +186,14 @@ context, in assembly order, after the existing newline normalization and truncat
 distinguishes `repository` from `global`; version 1.0.0's fixed root-file selection currently emits
 only `repository` sources and does not add any global-file discovery.
 
-`statuses` lists machine-readable collection and render conditions that previously appeared only inside `context` Markdown — plus the nested-context truncation flags, which exist only in machine form: skipped or absent sources, truncated sources, unreadable directory-tree entries, directory-tree entries whose directory holds more entries than one enumeration examines, sections omitted under the global output budget, truncated working-tree, declared-command or directory-tree listings, and truncated nested-`AGENTS.md` presence reports. A skipped or absent source reports the code of the condition the collector observed (`not_present`, `skipped_symlink`, `skipped_not_regular`, `skipped_encoding`, `skipped_unreadable`); the sentence in `context` is rendered from that same condition, so wording and code cannot drift apart. Each entry has stable `code`, `subject_kind`, and `subject` fields. The two `nested_agents_*` codes mirror the `nested_context` truncation booleans for consumers that branch only on `statuses`; the full `nested_context` object remains a first-class field, never folded into `statuses`. Callers can ignore `statuses` safely.
+`statuses` lists skipped or absent sources, truncated sources, unreadable tree entries,
+directories whose listing exceeds its retention cap, globally omitted sections, and truncated
+working-tree, command, tree or nested-`AGENTS.md` listings. A skipped or absent source reports
+the observed condition (`not_present`, `skipped_symlink`, `skipped_not_regular`,
+`skipped_encoding`, `skipped_unreadable`); its sentence in `context` comes from that same
+condition. Each entry has stable `code`, `subject_kind`, and `subject` fields. The two
+`nested_agents_*` codes mirror the `nested_context` truncation booleans; the complete object
+remains a separate field. Callers can ignore `statuses` safely.
 
 The optional `selection` object is present only on a rendered `AGENTS.md` source. Its section entries
 contain heading, heading level, and fixed selection reasons; it never contains the original focus or
@@ -206,7 +213,7 @@ separator, with the array's brackets charged to the first entry — so the emitt
 more than the budget it declares. Because quoting is counted, an array already near the cap can
 report one path fewer than an older release did, and then says so through `list_truncated`.
 `scan_truncated` means the depth (4) or directory-count (2,000) budget was reached, a directory
-held more entries than one enumeration examines (1,024), or a directory or entry could not be
+held more entries than one listing retains (1,024), or a directory or entry could not be
 read, so absence of a path is not proof of absence of the file. Nested paths
 are sanitized with the same escaping the Markdown uses for repository-derived text, so a nested name
 the filesystem could not decode never breaks the document;
@@ -215,6 +222,16 @@ see “Limits” for the root paths that are emitted verbatim. The corresponding
 Presence is not instruction: whether a nested file applies, and its text, remain the caller's
 judgment; Markdown output is unchanged.
 
+Escaped names remain reversible and distinct: a literal backslash becomes `\\`, a backtick
+becomes `\x60`, ASCII controls and undecodable filesystem bytes become `\xNN`, and other
+non-printable Unicode characters become `\uNNNN` or `\UNNNNNNNN`. Printable Unicode stays
+unchanged. After JSON decoding, recover POSIX path bytes by reading escapes from left to right:
+`\\` yields one backslash byte, `\xNN` yields that byte, and Unicode escapes and ordinary
+characters yield their UTF-8 bytes. Thus a backtick, a literal `\x60`, an undecodable byte
+`0x80`, and Unicode `U+0080` all have different representations. This applies to nested paths
+and displayed tree/change/status names; the verbatim root/source paths retain their existing
+semantics.
+
 ### Compact model consumption (`--format json-compact`)
 
 `--format json-compact` emits a `schema_version` 4 document: exactly the version-3 document with
@@ -242,7 +259,7 @@ although 1.1.0 added the top-level `statuses` key. From release 1.2.0 onward eac
 names exactly one key set, and a new number is issued whenever a key set would otherwise be reused.
 
 The JSON schema version and package version are independent: this build emits `schema_version` `3`
-for `--format json` and `4` for `--format json-compact`, while `tool.version` is `1.3.2`. Version 1
+for `--format json` and `4` for `--format json-compact`, while `tool.version` is `1.3.3`. Version 1
 and 2 are the exact shapes already published in release 1.2.0 and are never reused: because
 `nested_context` changes the default document's key set, version 3 names the current full-document
 key set and version 4 names the compact projection.
@@ -316,10 +333,11 @@ bullet is a per-component, read or capture bound, as each one states:
   16 KiB, including a 4-KiB maximum small head
 - `README.md`: 16 KiB
 - Each entry file: 8 KiB
-- All entry-file bodies: 24 KiB
+- All entry-file bodies: 24 KiB, including truncation markers. Room is reserved for markers
+  on later text sources, so exhausting the budget never hides that their bodies were cut.
 - Declared commands: 8 KiB
 - Directory tree: 12 KiB of listing body, 300 entries, and depth 2. Each directory is
-  enumerated up to 512 entries, keeping the alphabetically first names so the listing never
+  retains and classifies up to 512 entries, keeping the alphabetically first names so the listing never
   depends on operating system order. A directory that holds more is reported by a single
   `Listing incomplete:` line stating the total, the limit and up to three names, and by at most
   eight `directory_listing_incomplete` status entries naming individual directories plus one
@@ -330,8 +348,10 @@ bullet is a per-component, read or capture bound, as each one states:
   alphabetical prefix and the entry budget kept it, so capped siblings displaced by the budget are
   disclosed as their parent's truncation rather than as separate numbers.
   Three limits act in sequence and a name survives only if all three leave room. The 512-entry
-  enumeration limit decides which names a directory offers at all; above it only an alphabetical
-  prefix is ever seen. The 300-entry item budget is then shared between a directory's
+  retention limit decides which names a directory offers at all; above it only an alphabetical
+  prefix is classified. All names must still be scanned to find that prefix, subject to the
+  separate hard name-scan bound below; the retention cap bounds memory and classification work.
+  The 300-entry item budget is then shared between a directory's
   subdirectories and its non-directories: each may take up to half of what remains before the other
   claims the surplus, which stops alphabetically-earlier directories from evicting every file, but
   it is a share rather than a floor -- with a single slot left the non-directories take it. The 12
@@ -350,8 +370,14 @@ bullet is a per-component, read or capture bound, as each one states:
   fence say so. The heading and the code-fence lines are not metered, so the whole Markdown
   section can exceed 12 KiB by that fixed few dozen bytes.
 - Nested `AGENTS.md` presence scan: depth 4, 2,000 directories, at most 32 reported paths, a
-  4 KiB budget metered on the emitted array, and at most 1,024 entries examined per directory;
-  file contents are never read
+  4 KiB budget metered on the emitted array, and at most 1,024 entries retained and classified
+  per directory. Names are scanned to select that prefix, subject to the separate hard
+  name-scan bound below; file contents are never read
+- Directory name scans stop on the first entry beyond 65,536 names per directory. An
+  over-limit directory's entire partial prefix is discarded to keep results independent of
+  operating system order. The tree emits `Skipped: directory name scan limit reached.` and
+  a `directory_scan_limit_exceeded` status; the nested presence scan sets `scan_truncated`.
+  This bounds name iteration, not elapsed time on a blocked filesystem call.
 - Working-tree changes: 100 paths and 4 KiB
 - Recent commits: 8
 - JSON-only listings have no byte budget of their own: `statuses` subjects are escaped names bounded
@@ -359,6 +385,7 @@ bullet is a per-component, read or capture bound, as each one states:
   repository root the filesystem could not decode makes the machine formats exit 1 where Markdown
   still renders
 - Git subprocess output: 16 MiB (bounded while reading)
+- Git status preflight: at most 128 repositories, including initialized nested submodules
 - Candidate file validation: 16 MiB hard read bound
 
 Truncation occurs only at complete UTF-8 and line boundaries and is marked explicitly.
@@ -382,6 +409,13 @@ the remote.
   this is normal after cloning an empty remote.
 - `Ahead / behind: not available` means the commit relationship cannot currently be computed.
   Counts are reported only when the configured upstream commit is available locally.
+- Executable Git clean/process filters can run during `status`, even with optional locks
+  disabled. Before reading status, the loader checks effective repository configuration,
+  including includes, worktree configuration and initialized nested submodules. A non-empty
+  clean/process command causes a safe error with no stdout, even if no current attribute uses
+  it. Disabling a driver silently would change cleanliness semantics. Filter-dependent repositories
+  (including locally configured Git LFS drivers) therefore need ordinary Git inspection outside
+  this loader. Git protocols are also disabled to prevent lazy object retrieval.
 
 ## Exit Codes
 
@@ -394,7 +428,7 @@ or candidate-file content.
 
 ## Not Included
 
-Version 1.3.2 does not provide AI summaries, project-type detection, loading or transport of
+Version 1.3.3 does not provide AI summaries, project-type detection, loading or transport of
 nested `AGENTS.md` contents (the JSON `nested_context` field reports bounded existence only),
 Memory retrieval, semantic ranking, ignore-rule parsing, plugins, profiles, caches, databases,
 network services, MCP, daemons, GUIs, CI/CD, telemetry, or automatic updates.
@@ -407,6 +441,17 @@ Run the complete local check:
 just check
 ```
 
+The lockfile uses public PyPI artifact URLs; no organization mirror or local Renovate preset
+is needed. Renovate keeps scheduled, rate-limited updates and manual merges using a public
+recommended preset plus the repository's explicit settings. Python 3.12 remains the tested
+runtime; widening that range requires testing those interpreters first.
+
+Git test fixtures discard inherited `GIT_*` routing/configuration before creating repositories.
+Permission-sensitive tests must run as a non-root user. Gitea uses `just ci-check`: non-root
+runners execute directly; root containers use `runuser` with an existing account named by
+`CONTEXT_LOADER_CI_USER` (default `ubuntu`). That account must be able to execute the installed
+`uv`, Python and `just`. No `sudo` dependency is required for this CI step.
+
 ## Version maintenance
 
 The versions in `pyproject.toml` and `context_loader/__init__.py`, the `tool_version` in
@@ -427,6 +472,11 @@ only verifies the public release, mirrors its exact formal tag object if missing
 the Gitea Release record. It builds no package and has no PyPI publishing credentials.
 No private endpoint or credential is needed on GitHub.
 
+For environments that permit direct public reads but share an exhausted proxy quota,
+set the Gitea Actions repository variable `RELEASE_PUBLIC_API_DIRECT=true`. The record
+step appends only public GitHub API/PyPI hosts to the existing proxy bypass lists. Without
+this explicit option, the workflow uses its inherited proxy settings.
+
 Release checks use Python 3.12, Git, and the runner's existing OpenSSL CLI. They compare downloaded
 PyPI file bytes, metadata and SHA-256, plus the publisher/tag/commit claims in PyPI's HTTPS-served
 provenance. This is an identity check, not an independent cryptographic Sigstore verifier.

{context_loader-1.3.2 → context_loader-1.3.3}/context_loader/__init__.py

@@ -1,3 +1,3 @@
 """Project Context Loader."""
 
-__version__ = "1.3.2"
+__version__ = "1.3.3"

{context_loader-1.3.2 → context_loader-1.3.3}/context_loader/application.py

@@ -26,7 +26,6 @@ from .model import (
 from .render import (
     RenderedSourceBody,
     render_markdown_with_details,
-    rendered_source_contents,
 )
 
 # Each value names one exact document shape and is never reused: 1 and 2 are the
@@ -70,9 +69,7 @@ class ContextStatus:
     code: str
     subject_kind: str
     subject: str
-    # The raw fact behind the displayed subject. Display escaping is not injective, so
-    # deduplication must key on this and never on `subject`, or two different directories
-    # could collapse into one claim. It is not serialized.
+    # Deduplicate raw facts independently of display formatting. Not serialized.
     identity: str = field(default="", compare=False)
 
 
@@ -191,7 +188,19 @@ def _build_statuses(
     for entry in project.directory_tree.entries:
         if entry.kind == "unreadable_directory":
             subject = entry.path if entry.path else "."
-            statuses.append(_status("unreadable", "tree_entry", display_text(subject)))
+            statuses.append(
+                _status("unreadable", "tree_entry", display_text(subject), identity=subject)
+            )
+        elif entry.kind == "scan_limit_directory":
+            subject = entry.path if entry.path else "."
+            statuses.append(
+                _status(
+                    "directory_scan_limit_exceeded",
+                    "tree_entry",
+                    display_text(subject),
+                    identity=subject,
+                )
+            )
     tree = project.directory_tree
     named = list(dict.fromkeys(tree.incomplete_directories))
     for path in named:
@@ -212,7 +221,7 @@ def _build_statuses(
                 "directory_listing_incomplete",
                 "tree",
                 f"{tree.incomplete_count} directories exceeded the "
-                f"{tree.enumeration_limit}-entry per-directory enumeration limit; "
+                f"{tree.enumeration_limit}-entry per-directory retention limit; "
                 f"{unnamed} further {stem} not named individually",
                 identity=f"aggregate:{tree.incomplete_count}:{unnamed}",
             )
@@ -254,7 +263,7 @@ def load_project_context(
         raise ContextLoaderError(str(exc), exit_code=2) from None
     rendered = render_markdown_with_details(state, project)
     context = rendered.output.decode("utf-8")
-    rendered_bodies = rendered_source_contents(project, rendered.included_sections)
+    rendered_bodies = rendered.source_bodies
     sources = _sources(state.repository, rendered_bodies)
     statuses = _build_statuses(
         project,

{context_loader-1.3.2 → context_loader-1.3.3}/context_loader/collect.py

@@ -13,6 +13,7 @@ from dataclasses import dataclass, replace
 from pathlib import Path, PurePosixPath
 
 from .filesystem import (
+    DirectoryScanLimitError,
     enumerate_directory,
     open_bounded_regular_file,
     open_child_directory,
@@ -185,6 +186,7 @@ def _ordered_reasons(reasons: set[str] | frozenset[str]) -> tuple[str, ...]:
 
 
 _AUDIT_EMPTY_LIST_LINE = "- None."
+_AUDIT_NO_INDEX_LINE = "- Omitted content has no available heading index; read the source path."
 
 
 def _audit_heading(heading: str) -> str:
@@ -198,6 +200,11 @@ def _audit_index_line(entry: AgentsSectionAuditEntry) -> str:
     return f"- H{entry.heading_level} {_audit_heading(entry.heading)}"
 
 
+def _audit_selected_line(entry: AgentsSectionAuditEntry) -> str:
+    label = "Document head" if entry.heading_level == 0 else _audit_heading(entry.heading)
+    return f"- {label} — `{', '.join(entry.reasons)}`"
+
+
 def render_agents_selection_audit(audit: AgentsSelectionAudit) -> str:
     """Render the bounded, prompt-free AGENTS selection audit and fail-safe index."""
     lines = [
@@ -212,9 +219,7 @@ def render_agents_selection_audit(audit: AgentsSelectionAudit) -> str:
     ]
     if audit.selected_sections:
         for entry in audit.selected_sections:
-            label = "Document head" if entry.heading_level == 0 else _audit_heading(entry.heading)
-            reasons = ", ".join(entry.reasons)
-            lines.append(f"- {label} — `{reasons}`")
+            lines.append(_audit_selected_line(entry))
     else:
         lines.append(_AUDIT_EMPTY_LIST_LINE)
     lines.extend(
@@ -229,7 +234,7 @@ def render_agents_selection_audit(audit: AgentsSelectionAudit) -> str:
     else:
         lines.append(_AUDIT_EMPTY_LIST_LINE)
         if audit.truncated and not audit.index_truncated:
-            lines.append("- Omitted content has no available heading index; read the source path.")
+            lines.append(_AUDIT_NO_INDEX_LINE)
     if audit.index_truncated:
         lines.append("- Additional headings omitted from this index by the AGENTS budget.")
     if audit.parse_fallback:
@@ -329,7 +334,11 @@ def _small_head_end(content: str, sections: tuple[MarkdownSection, ...]) -> int:
 def _section_relevance(
     section: MarkdownSection, signals: _SelectionSignals
 ) -> tuple[int, frozenset[str]]:
-    heading_tokens = _matching_tokens(section.heading, _MATCH_TOKEN_STOPWORDS)
+    heading_tokens = frozenset(
+        token
+        for token in section.normalized_heading.split()
+        if len(token) >= 3 and token not in _MATCH_TOKEN_STOPWORDS
+    )
     section_tokens = _matching_tokens(section.text, _MATCH_TOKEN_STOPWORDS)
     body_tokens = section_tokens - heading_tokens
     score = 0
@@ -343,9 +352,9 @@ def _section_relevance(
 
     path_heading = signals.path_tokens & heading_tokens
     path_body = signals.path_tokens & body_tokens
-    normalized_section = _normalized_text(section.text)
     exact_path = bool(
-        signals.normalized_path and _normalized_text(signals.normalized_path) in normalized_section
+        signals.normalized_path
+        and _normalized_text(signals.normalized_path) in _normalized_text(section.text)
     )
     if exact_path or path_heading or path_body:
         reasons.add("path_match")
@@ -522,50 +531,172 @@ def _select_agents_content(source: CollectedFile, signals: _SelectionSignals) ->
         return _bounded_head_fallback(source, parse_fallback=True)
 
     head_end = _small_head_end(source.content, sections)
-    selected_indices: frozenset[int] = frozenset()
-    reasons: dict[int, set[str]] = {}
+    selected_indices = {index for index, section in enumerate(sections) if section.end <= head_end}
+    reasons: dict[int, set[str]] = {index: {"head"} for index in selected_indices}
     ranked: list[tuple[int, int, frozenset[str]]] = []
     for index, section in enumerate(sections):
-        score, section_reasons = _section_relevance(section, signals)
-        if score >= 4:
-            ranked.append((score, index, section_reasons))
+        if signals.focus_tokens or signals.path_tokens or signals.normalized_path:
+            score, section_reasons = _section_relevance(section, signals)
+            if score >= 4:
+                ranked.append((score, index, section_reasons))
     ranked.sort(key=lambda item: (-item[0], sections[item[1]].start))
 
+    # Sections are disjoint. Candidate admission therefore needs only the bytes,
+    # characters and audit lines changed by that section and its (at most six)
+    # parents, rather than rebuilding every section/index for every candidate.
+    extra_bytes = [
+        len(source.content[max(head_end, section.start) : section.end].encode("utf-8"))
+        if section.end > head_end
+        else 0
+        for section in sections
+    ]
+    index_sizes = [
+        len(
+            _audit_index_line(AgentsSectionAuditEntry(s.heading, s.heading_level, ())).encode(
+                "utf-8"
+            )
+        )
+        + 1
+        for s in sections
+    ]
+    selected_sizes = {
+        index: len(
+            _audit_selected_line(
+                AgentsSectionAuditEntry(
+                    sections[index].heading, sections[index].heading_level, ("head",)
+                )
+            ).encode("utf-8")
+        )
+        + 1
+        for index in selected_indices
+    }
+    selected_lines = sum(selected_sizes.values())
+    document_head_end = sections[0].start if sections else len(source.content)
+    if document_head_end and head_end:
+        selected_lines += (
+            len(
+                _audit_selected_line(AgentsSectionAuditEntry("Document head", 0, ("head",))).encode(
+                    "utf-8"
+                )
+            )
+            + 1
+        )
+    content_bytes = len(source.content[:head_end].encode("utf-8"))
+    chars_selected = head_end
+    index_count = len(sections) - len(selected_indices)
+    index_lines = sum(
+        size for index, size in enumerate(index_sizes) if index not in selected_indices
+    )
+    first_index = len(selected_indices)
+    placeholder_bytes = len(_AUDIT_EMPTY_LIST_LINE.encode("utf-8")) + 1
+    no_index_bytes = len(_AUDIT_NO_INDEX_LINE.encode("utf-8")) + 1
+    empty_sizes = {
+        (truncated, index_truncated): len(
+            render_agents_selection_audit(
+                AgentsSelectionAudit(
+                    source="AGENTS.md",
+                    selected_sections=(),
+                    indexed_only_sections=(),
+                    chars_selected=0,
+                    chars_omitted=0,
+                    truncated=truncated,
+                    source_scan_truncated=source.truncated,
+                    index_truncated=index_truncated,
+                )
+            ).encode("utf-8")
+        )
+        for truncated in (False, True)
+        for index_truncated in (False, True)
+    }
+
+    def minimum_cost(
+        body_bytes: int,
+        chars: int,
+        selected_line_bytes: int,
+        remaining_count: int,
+        remaining_lines: int,
+        first_remaining: int,
+    ) -> int:
+        omitted = max(0, source.source_characters - chars)
+        truncated = omitted > 0 or source.truncated
+        common = body_bytes + len(str(chars)) + len(str(omitted)) - 2
+        if selected_line_bytes:
+            common += selected_line_bytes - placeholder_bytes
+        full = common + empty_sizes[truncated, False]
+        if remaining_count:
+            full += remaining_lines - placeholder_bytes
+            if truncated:
+                full -= no_index_bytes
+        fitted = common + empty_sizes[truncated, True]
+        if remaining_count > 1:
+            # A very short first index line can cost less than the empty placeholder.
+            fitted += min(0, index_sizes[first_remaining] - placeholder_bytes)
+        return min(full, fitted)
+
     budget_fallback: set[int] = set()
     for _score, index, section_reasons in ranked:
-        trial_indices = set(selected_indices)
-        trial_reasons = {key: set(value) for key, value in reasons.items()}
-        trial_indices.add(index)
-        trial_reasons.setdefault(index, set()).update(section_reasons)
+        trial_reasons = {index: reasons.get(index, set()) | set(section_reasons)}
         parent = sections[index].parent_index
         while parent is not None:
-            trial_indices.add(parent)
-            trial_reasons.setdefault(parent, set()).add("parent_context")
+            trial_reasons[parent] = reasons.get(parent, set()) | {"parent_context"}
             parent = sections[parent].parent_index
-        trial_content, trial_audit = _selection_state(
-            source.content,
-            sections,
-            head_end,
-            frozenset(trial_indices),
-            trial_reasons,
-            frozenset(budget_fallback),
-            parse_fallback=False,
-            source_scan_truncated=source.truncated,
-            source_characters=source.source_characters,
+        new_indices = trial_reasons.keys() - selected_indices
+        trial_bytes = content_bytes + sum(extra_bytes[item] for item in new_indices)
+        trial_chars = chars_selected + sum(
+            sections[item].end - max(head_end, sections[item].start) for item in new_indices
         )
-        try:
-            _fit_agents_index(trial_content, trial_audit)
-        except RuntimeError:
+        trial_sizes = {
+            item: len(
+                _audit_selected_line(
+                    AgentsSectionAuditEntry(
+                        sections[item].heading,
+                        sections[item].heading_level,
+                        _ordered_reasons(item_reasons),
+                    )
+                ).encode("utf-8")
+            )
+            + 1
+            for item, item_reasons in trial_reasons.items()
+        }
+        trial_selected_lines = selected_lines + sum(
+            size - selected_sizes.get(item, 0) for item, size in trial_sizes.items()
+        )
+        trial_index_count = index_count - len(new_indices)
+        trial_index_lines = index_lines - sum(index_sizes[item] for item in new_indices)
+        trial_first = first_index
+        while trial_first < len(sections) and (
+            trial_first in selected_indices or trial_first in new_indices
+        ):
+            trial_first += 1
+        if (
+            minimum_cost(
+                trial_bytes,
+                trial_chars,
+                trial_selected_lines,
+                trial_index_count,
+                trial_index_lines,
+                trial_first,
+            )
+            > AGENTS_LIMIT_BYTES
+        ):
             budget_fallback.add(index)
         else:
-            selected_indices = frozenset(trial_indices)
-            reasons = trial_reasons
+            selected_indices.update(new_indices)
+            reasons.update(trial_reasons)
+            selected_sizes.update(trial_sizes)
+            content_bytes, chars_selected = trial_bytes, trial_chars
+            selected_lines = trial_selected_lines
+            index_count, index_lines, first_index = (
+                trial_index_count,
+                trial_index_lines,
+                trial_first,
+            )
 
     content, audit = _selection_state(
         source.content,
         sections,
         head_end,
-        selected_indices,
+        frozenset(selected_indices),
         reasons,
         frozenset(budget_fallback),
         parse_fallback=False,
@@ -837,6 +968,9 @@ def _collect_directory_tree(root: Path) -> DirectoryTree:
                 continue
             try:
                 walk(child_descriptor, entry_path, depth + 1)
+            except DirectoryScanLimitError:
+                collected[index] = TreeEntry(entry_path, "scan_limit_directory")
+                truncated = True
             except OSError:
                 mark_unreadable(index, entry_path)
             finally:
@@ -849,6 +983,9 @@ def _collect_directory_tree(root: Path) -> DirectoryTree:
     try:
         try:
             walk(root_descriptor, "", 0)
+        except DirectoryScanLimitError:
+            collected.append(TreeEntry("", "scan_limit_directory"))
+            truncated = True
         except OSError:
             if not collected:
                 collected.append(TreeEntry("", "unreadable_directory"))

{context_loader-1.3.2 → context_loader-1.3.3}/context_loader/filesystem.py

@@ -1,8 +1,8 @@
 """Safe, bounded filesystem primitives shared by every context collection scan.
 
 Everything here is descriptor-relative, never follows a symlink across a boundary it
-does not report, and caps its own work: this module reads directory entries and file
-bytes, and it reports what it observed as typed availability reasons rather than as
+does not report, and bounds retained entries and file reads. It reports observations
+as typed availability reasons rather than as
 prose, so callers cannot lose the difference between absence and a bounded claim.
 """
 
@@ -18,7 +18,7 @@ from dataclasses import dataclass
 from heapq import nsmallest
 from pathlib import Path
 
-from .model import FILE_SCAN_LIMIT_BYTES, Availability
+from .model import DIRECTORY_NAME_SCAN_LIMIT_ENTRIES, FILE_SCAN_LIMIT_BYTES, Availability
 
 DIRECTORY_OPEN_FLAGS = os.O_RDONLY | os.O_CLOEXEC | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0)
 REGULAR_FILE_OPEN_FLAGS = os.O_RDONLY | os.O_CLOEXEC | os.O_NONBLOCK | getattr(os, "O_NOFOLLOW", 0)
@@ -38,31 +38,37 @@ class DirectoryEntryFacts:
 class DirectoryListing:
     """A sorted, capped enumeration of one directory.
 
-    ``capped`` is the honest claim that the directory holds more entries than were
-    examined, so a caller can never present this listing as complete.
+    ``capped`` means more names were scanned than were retained and classified,
+    so a caller can never present this listing as complete.
     """
 
     entries: tuple[DirectoryEntryFacts, ...]
     capped: bool
 
 
+class DirectoryScanLimitError(OSError):
+    """The name scan exceeded its hard cap; no alphabetical prefix is trustworthy."""
+
+
 def display_text(value: str) -> str:
     r"""Render one filesystem or Git string as printable, encodable ASCII-safe text.
 
-    Backticks, lone surrogates produced by ``surrogateescape`` decoding, and every
-    other non-printable codepoint become ``\xNN``/``\uNNNN``/``\UNNNNNNNN`` escapes so
-    the character can cross the JSON and Markdown serialization boundaries intact.
+    Escape backslashes as well as backticks and non-printable codepoints so names
+    remain distinguishable. ``\x80`` through ``\xff`` represent undecodable bytes;
+    Unicode controls above ASCII use ``\uNNNN`` instead of sharing those escapes.
     """
     rendered: list[str] = []
     for character in value:
         codepoint = ord(character)
-        if character == "`":
+        if character == "\\":
+            rendered.append(r"\\")
+        elif character == "`":
             rendered.append(r"\x60")
         elif 0xDC80 <= codepoint <= 0xDCFF:
             rendered.append(f"\\x{codepoint - 0xDC00:02x}")
         elif character.isprintable():
             rendered.append(character)
-        elif codepoint <= 0xFF:
+        elif codepoint <= 0x7F:
             rendered.append(f"\\x{codepoint:02x}")
         elif codepoint <= 0xFFFF:
             rendered.append(f"\\u{codepoint:04x}")
@@ -93,6 +99,8 @@ def open_child_directory(parent_descriptor: int, name: str) -> int:
 def _counted(entries: Iterator[os.DirEntry[str]], counter: list[int]) -> Iterator[os.DirEntry[str]]:
     for entry in entries:
         counter[0] += 1
+        if counter[0] > DIRECTORY_NAME_SCAN_LIMIT_ENTRIES:
+            raise DirectoryScanLimitError("directory name scan exceeded the safety limit")
         yield entry
 
 
@@ -117,7 +125,11 @@ def enumerate_directory(directory_descriptor: int, limit: int) -> DirectoryListi
     rather than whatever the operating system happened to yield first, so a capped
     listing is reproducible. Memory stays bounded by ``limit`` because entries are
     selected while the scan iterator is consumed, and only the retained entries are
-    classified. ``OSError`` propagates when the directory itself cannot be read, so
+    classified. All names must be scanned to establish that alphabetical prefix;
+    ``limit`` bounds retention/classification, not iteration or elapsed time. The
+    independent name-scan cap raises ``DirectoryScanLimitError`` and discards the
+    entire prefix rather than reporting an OS-order-dependent partial result.
+    ``OSError`` propagates when the directory itself cannot be read, so
     each caller keeps its own meaning for an unreadable directory.
     """
     if limit < 1:

{context_loader-1.3.2 → context_loader-1.3.3}/context_loader/git.py

@@ -15,6 +15,7 @@ GIT_EXECUTABLE = "/usr/bin/git"
 GIT_TIMEOUT_SECONDS = 30
 MAX_GIT_OUTPUT_BYTES = 16 * 1024 * 1024
 MAX_RECENT_COMMITS = 8
+MAX_STATUS_REPOSITORIES = 128
 
 _OID_PATTERN = re.compile(r"(?:[0-9a-f]{40}|[0-9a-f]{64})\Z")
 _GIT_PREFIX = (
@@ -37,10 +38,13 @@ _GIT_PREFIX = (
     "i18n.logOutputEncoding=UTF-8",
     "-c",
     "log.showSignature=false",
+    "-c",
+    "protocol.allow=never",
 )
 _GIT_ENVIRONMENT = MappingProxyType(
     {
         "GIT_ATTR_NOSYSTEM": "1",
+        "GIT_ALLOW_PROTOCOL": "",
         "GIT_CONFIG_COUNT": "0",
         "GIT_CONFIG_GLOBAL": "/dev/null",
         "GIT_CONFIG_NOSYSTEM": "1",
@@ -314,7 +318,65 @@ def _upstream_state(repo: Path, branch_name: str | None) -> tuple[str, str]:
     return upstream, f"{counts[0].decode('ascii')} / {counts[1].decode('ascii')}"
 
 
+def _ensure_safe_status(repo: Path) -> None:
+    """Reject executable conversions before status can refresh any index entry.
+
+    Attributes can select clean/process drivers even during a read-only status.
+    Ignoring those drivers would change Git's cleanliness semantics, so fail closed
+    instead. Status also inspects initialized submodules; check their own config
+    without invoking `submodule foreach` or any repository-supplied command.
+    """
+    pending = [repo]
+    seen: set[Path] = set()
+    while pending:
+        current = pending.pop()
+        identity = current.resolve()
+        if identity in seen:
+            raise ContextLoaderError("unable to safely inspect cyclic submodule state")
+        seen.add(identity)
+        if len(seen) > MAX_STATUS_REPOSITORIES:
+            raise ContextLoaderError("repository submodule inspection exceeded the safety limit")
+        filters = _run_git(
+            current,
+            ("config", "--null", "--get-regexp", r"^filter\..*\.(clean|process)$"),
+            check=False,
+        )
+        if filters.returncode not in (0, 1):
+            raise ContextLoaderError("unable to safely inspect repository Git filters")
+        filter_commands: dict[bytes, bytes] = {}
+        for record in filters.stdout.split(b"\0"):
+            if not record:
+                continue
+            key, separator, value = record.partition(b"\n")
+            if not key or not separator:
+                raise ContextLoaderError("unable to safely inspect repository Git filters")
+            filter_commands[key] = value
+        if any(filter_commands.values()):
+            raise ContextLoaderError(
+                "repository or submodule config enables Git clean/process filters; "
+                "unable to safely inspect working-tree state"
+            )
+        index = _run_git(current, ("ls-files", "--stage", "-z"))
+        children: set[Path] = set()
+        for record in index.stdout.split(b"\0"):
+            metadata, separator, raw_path = record.partition(b"\t")
+            if metadata.split(b" ", 1)[0] != b"160000":
+                continue
+            if not separator or not raw_path:
+                raise ContextLoaderError("unable to parse repository submodule state")
+            path = Path(_decode_path(raw_path))
+            if path.is_absolute() or ".." in path.parts:
+                raise ContextLoaderError("unable to safely inspect repository submodule state")
+            child = current / path
+            if (child / ".git").exists():
+                children.add(child)
+        pending.extend(sorted(children))
+        if len(seen) + len(pending) > MAX_STATUS_REPOSITORIES:
+            raise ContextLoaderError("repository submodule inspection exceeded the safety limit")
+
+
 def _working_tree_changes(repo: Path) -> tuple[WorkingTreeChange, ...]:
+    _ensure_safe_status(repo)
     result = _run_git(
         repo,
         (

{context_loader-1.3.2 → context_loader-1.3.3}/context_loader/model.py

@@ -22,9 +22,10 @@ DECLARED_COMMANDS_LIMIT_BYTES = 8 * 1024
 DIRECTORY_TREE_LIMIT_BYTES = 12 * 1024
 DIRECTORY_TREE_MAX_ITEMS = 300
 DIRECTORY_TREE_MAX_DEPTH = 2
+DIRECTORY_NAME_SCAN_LIMIT_ENTRIES = 65_536
 # Deliberately above the item budget: which of a directory's own entries are shown must
 # be decided by the item budget and its root-file guarantee, not by enumeration order.
-# It is still a hard cap, so one huge directory can never be materialised in memory.
+# This caps retention/classification; choosing the prefix still scans all names.
 DIRECTORY_TREE_MAX_ENTRIES_PER_DIRECTORY = 512
 # A capped directory is reported once as a number plus a bounded set of examples, so the
 # completeness claim cannot itself inflate the section it describes.
@@ -35,13 +36,12 @@ NESTED_AGENTS_MAX_DIRECTORIES = 2_000
 NESTED_AGENTS_MAX_FILES = 32
 NESTED_AGENTS_MAX_LIST_BYTES = 4 * 1024
 # The presence scan inspects names only and lists no directory entries at all, so it can
-# examine a wider prefix per directory than the tree does; exceeding it is scan truncation.
+# retain a wider prefix per directory than the tree does; exceeding it is scan truncation.
 NESTED_AGENTS_MAX_ENTRIES_PER_DIRECTORY = 1_024
 NESTED_AGENTS_EXCLUDED_DIRECTORIES = frozenset(
     {".git", ".venv", "node_modules", "site-packages", "venv"}
 )
 FILE_SCAN_LIMIT_BYTES = 16 * 1024 * 1024
-MAX_FILE_SCAN_BYTES = FILE_SCAN_LIMIT_BYTES
 TRUNCATION_MARKER = "… truncated by context-loader …"
 
 ENTRY_FILE_SPECS = (
@@ -148,7 +148,7 @@ class DirectoryTree:
     """A bounded directory listing that never overstates what it examined.
 
     ``truncated`` claims that entries exist beyond this listing. A directory holding more
-    entries than one enumeration examines is counted in ``incomplete_count`` against
+    entries than one listing retains is counted in ``incomplete_count`` against
     ``enumeration_limit``, and ``incomplete_directories`` retains only the first
     ``DIRECTORY_TREE_INCOMPLETE_STATUS_LIMIT`` of them, so a partial listing of a directory is
     never presented as a complete one and the claim stays bounded however many hit the cap.

{context_loader-1.3.2 → context_loader-1.3.3}/context_loader/render.py

@@ -41,6 +41,7 @@ class MarkdownRender:
     changes_truncated: bool
     commands_truncated: bool
     tree_truncated: bool
+    source_bodies: tuple[RenderedSourceBody, ...]
 
 
 @dataclass(frozen=True, slots=True)
@@ -125,11 +126,10 @@ def _file_body(source: CollectedFile, limit: int) -> tuple[str, bool] | None:
     return body, truncated
 
 
-def _file_payload(source: CollectedFile, limit: int) -> str:
-    body = _file_body(source, limit)
+def _file_payload(source: CollectedFile, body: RenderedSourceBody | None) -> str:
     if body is None:
         return _unavailable_sentence(source.reason)
-    return _fenced(source.language, body[0])
+    return _fenced(source.language, body.body)
 
 
 def _change_lines(state: RepositoryState) -> tuple[list[str], bool]:
@@ -170,13 +170,15 @@ def _render_git_state(state: RepositoryState) -> str:
     return "\n".join(lines)
 
 
-def _render_source_section(title: str, source: CollectedFile, limit: int) -> str:
+def _render_source_section(
+    title: str, source: CollectedFile, body: RenderedSourceBody | None
+) -> str:
     parts = [
         f"## {title}",
         "",
         f"Source: `{source.name}`",
         "",
-        _file_payload(source, limit),
+        _file_payload(source, body),
     ]
     if source.selection is not None:
         parts.extend(("", render_agents_selection_audit(source.selection)))
@@ -226,30 +228,44 @@ def _entry_body(source: CollectedFile, remaining: int) -> tuple[str | None, int,
     if not source.is_text:
         return None, 0, False
     encoded_size = len(source.content.encode())
-    aggregate_truncated = encoded_size > remaining
-    needs_marker = source.truncated or aggregate_truncated
+    limit = max(0, min(remaining, ENTRY_FILE_LIMIT_BYTES))
+    needs_marker = source.truncated or encoded_size > limit
     marker_size = len(TRUNCATION_MARKER.encode()) if needs_marker else 0
-    content_limit = min(remaining, ENTRY_FILE_LIMIT_BYTES - marker_size)
+    content_limit = limit - marker_size
     visible, was_cut = _truncate_at_line_boundary(source.content, max(0, content_limit))
     needs_marker = needs_marker or was_cut
-    body = f"{visible}{TRUNCATION_MARKER}" if needs_marker else visible
-    return body, len(visible.encode()), needs_marker
+    marker = TRUNCATION_MARKER if needs_marker and limit >= marker_size else ""
+    body = f"{visible}{marker}"
+    return body, len(body.encode()), needs_marker
 
 
-def _entry_payload(source: CollectedFile, remaining: int) -> tuple[str, int]:
-    body, consumed, _truncated = _entry_body(source, remaining)
-    if body is None:
-        return _unavailable_sentence(source.reason), consumed
-    return _fenced(source.language, body), consumed
+def _entry_bodies(entry_files: tuple[CollectedFile, ...]) -> tuple[RenderedSourceBody, ...]:
+    """Meter actual bodies, reserving room for later sources' truncation markers."""
+    marker_size = len(TRUNCATION_MARKER.encode())
+    reserved = sum(
+        marker_size
+        for source in entry_files
+        if source.is_text and (source.content or source.truncated)
+    )
+    used = 0
+    rendered: list[RenderedSourceBody] = []
+    for source in entry_files:
+        if source.is_text and (source.content or source.truncated):
+            reserved -= marker_size
+        remaining = max(0, ENTRY_FILES_TOTAL_LIMIT_BYTES - used - reserved)
+        body, consumed, truncated = _entry_body(source, remaining)
+        used += consumed
+        if body is not None:
+            rendered.append(RenderedSourceBody(source, body, truncated))
+    return tuple(rendered)
 
 
-def _render_entry_files(entry_files: tuple[CollectedFile, ...]) -> str:
+def _render_entry_files(
+    entry_files: tuple[CollectedFile, ...], bodies: dict[str, RenderedSourceBody]
+) -> str:
     parts = ["## Project Entry Files"]
-    used_content = 0
     for source in entry_files:
-        remaining = max(0, ENTRY_FILES_TOTAL_LIMIT_BYTES - used_content)
-        payload, consumed = _entry_payload(source, remaining)
-        used_content += consumed
+        payload = _file_payload(source, bodies.get(source.name))
         parts.extend(("", f"### `{source.name}`", "", payload))
     return "\n".join(parts)
 
@@ -286,6 +302,9 @@ def _tree_line(entry: TreeEntry) -> str:
         return f"{path}@"
     if entry.kind == "unreadable_directory":
         return f"{path}/ [Skipped: unreadable.]" if path else "Skipped: unreadable directory."
+    if entry.kind == "scan_limit_directory":
+        note = "Skipped: directory name scan limit reached."
+        return f"{path}/ [{note}]" if path else note
     return path
 
 
@@ -310,8 +329,8 @@ def _incomplete_directory_note(tree: DirectoryTree) -> str:
     limit = tree.enumeration_limit
     return (
         f"Listing incomplete: {tree.incomplete_count} {stem} held more entries than the "
-        f"{limit}-entry per-directory enumeration limit, so only an alphabetically first "
-        f"prefix of each was examined and the rest were neither examined nor listed; this "
+        f"{limit}-entry per-directory retention limit. All names were scanned to select an "
+        f"alphabetically first prefix; only that prefix was retained and classified. This "
         f"section also keeps only as many entries as its own entry and byte budgets allow. "
         f"Named here: {examples}."
     )
@@ -361,6 +380,8 @@ def render_markdown_with_details(state: RepositoryState, project: ProjectContext
     commands_section, commands_truncated = _render_commands(project.commands)
     changes_truncated = _change_lines(state)[1]
     tree_section, tree_truncated = _render_directory_tree(project.directory_tree)
+    all_bodies = _source_bodies(project)
+    bodies = {body.source.name: body for body in all_bodies}
     sections: list[tuple[str, str | None]] = [
         ("Git State", _render_git_state(state)),
         (
@@ -368,15 +389,17 @@ def render_markdown_with_details(state: RepositoryState, project: ProjectContext
             _render_source_section(
                 "Development Instructions",
                 project.instructions,
-                AGENTS_LIMIT_BYTES,
+                bodies.get(project.instructions.name),
             ),
         ),
         (
             "Project Overview",
-            _render_source_section("Project Overview", project.overview, README_LIMIT_BYTES),
+            _render_source_section(
+                "Project Overview", project.overview, bodies.get(project.overview.name)
+            ),
         ),
         ("Declared Commands", commands_section),
-        ("Project Entry Files", _render_entry_files(project.entry_files)),
+        ("Project Entry Files", _render_entry_files(project.entry_files, bodies)),
         ("Recent Commits", _render_recent_commits(state.commits)),
         ("Directory Tree", tree_section),
     ]
@@ -417,34 +440,48 @@ def render_markdown_with_details(state: RepositoryState, project: ProjectContext
         changes_truncated=changes_truncated,
         tree_truncated=tree_truncated,
         commands_truncated=commands_truncated,
+        source_bodies=_included_source_bodies(all_bodies, tuple(included_sections)),
     )
 
 
-def rendered_source_contents(
-    project: ProjectContext, included_sections: tuple[str, ...]
-) -> tuple[RenderedSourceBody, ...]:
-    """Return source-file bodies that actually appear in the final Markdown context."""
-    included = frozenset(included_sections)
+def _source_bodies(project: ProjectContext) -> tuple[RenderedSourceBody, ...]:
     rendered: list[RenderedSourceBody] = []
-    if "Development Instructions" in included:
-        body = _file_body(project.instructions, AGENTS_LIMIT_BYTES)
-        if body is not None:
-            rendered.append(RenderedSourceBody(project.instructions, body[0], body[1]))
-    if "Project Overview" in included:
-        body = _file_body(project.overview, README_LIMIT_BYTES)
+    for source, limit in (
+        (project.instructions, AGENTS_LIMIT_BYTES),
+        (project.overview, README_LIMIT_BYTES),
+    ):
+        body = _file_body(source, limit)
         if body is not None:
-            rendered.append(RenderedSourceBody(project.overview, body[0], body[1]))
-    if "Project Entry Files" in included:
-        used_content = 0
-        for source in project.entry_files:
-            remaining = max(0, ENTRY_FILES_TOTAL_LIMIT_BYTES - used_content)
-            body, consumed, truncated = _entry_body(source, remaining)
-            used_content += consumed
-            if body is not None:
-                rendered.append(RenderedSourceBody(source, body, truncated))
+            rendered.append(RenderedSourceBody(source, body[0], body[1]))
+    rendered.extend(_entry_bodies(project.entry_files))
     return tuple(rendered)
 
 
+def _included_source_bodies(
+    bodies: tuple[RenderedSourceBody, ...], included_sections: tuple[str, ...]
+) -> tuple[RenderedSourceBody, ...]:
+    included = frozenset(included_sections)
+    return tuple(
+        body
+        for body in bodies
+        if (
+            "Development Instructions"
+            if body.source.name == "AGENTS.md"
+            else "Project Overview"
+            if body.source.name == "README.md"
+            else "Project Entry Files"
+        )
+        in included
+    )
+
+
+def rendered_source_contents(
+    project: ProjectContext, included_sections: tuple[str, ...]
+) -> tuple[RenderedSourceBody, ...]:
+    """Return source-file bodies under the same budgets used by the Markdown renderer."""
+    return _included_source_bodies(_source_bodies(project), included_sections)
+
+
 def render_markdown(state: RepositoryState, project: ProjectContext) -> bytes:
     """Render all sections in fixed order without exceeding the global byte limit."""
     return render_markdown_with_details(state, project).output

{context_loader-1.3.2 → context_loader-1.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "context-loader"
-version = "1.3.2"
+version = "1.3.3"
 description = "Render deterministic local Git context for any executor"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{context_loader-1.3.2 → context_loader-1.3.3}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "context-loader"
-version = "1.3.2"
+version = "1.3.3"
 description = "Render deterministic local Git context for any executor"
 license = { file = "LICENSE" }
 readme = "README.md"

{context_loader-1.3.2 → context_loader-1.3.3}/tool_cli_contract.json

@@ -46,5 +46,5 @@
   ],
   "schema_version": 1,
   "tool_name": "context-loader",
-  "tool_version": "1.3.2"
+  "tool_version": "1.3.3"
 }