agent-wiki-cli 1.3.1__tar.gz → 1.4.0__tar.gz

{agent_wiki_cli-1.3.1/src/agent_wiki_cli.egg-info → agent_wiki_cli-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 1.3.1
+Version: 1.4.0
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License: MIT
@@ -301,6 +301,30 @@ llm-wiki install-hook --force
 
 ## Command Reference
 
+### Resource-aware execution
+
+In an interactive IDE or whenever host capacity is unknown, run one heavy gate
+at a time. Heavy gates include `context`, full tests, coverage, builds, browser
+suites, `sync`, `lint`, and `ci-check`. The supervising agent owns that
+schedule; subagents may inspect bounded files and diffs, but should not launch
+heavy gates unless explicitly assigned.
+
+Use `--jobs 1` for interactive source scans. `--jobs auto` remains an uncapped
+opt-in for an isolated terminal or a controlled CI runner with reserved
+capacity; do not combine it with nested heavy-gate fan-out. If ENOSPC, inotify,
+file-descriptor, severe swapping, or editor-responsiveness failures occur, stop
+launching work and do not retry the same burst. Recover capacity first, then
+attempt at most one manual retry with `--jobs 1`; unfinished gates remain
+inconclusive. Watcher-limit symptoms are host/IDE resource evidence, not proof
+that `llm-wiki` leaked a watcher.
+
+Before extraction, `sync`, `lint`, `ci-check`, and `context` write one flushed
+plan line to stderr without contaminating stdout, for example:
+
+```text
+Extractor plan: requested=auto resolved=20 eligible_parallel=2 effective_workers=2 parallel=python,typescript sequential=- cache_elided=-
+```
+
 ### `init`
 
 Scaffold the wiki structure and agent constraint file.
@@ -383,7 +407,7 @@ manifest.
 
 ```bash
 llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki
-llm-wiki sync --jobs auto --cache-stats --src-dir . --wiki-dir docs/llm_wiki
+llm-wiki sync --jobs 1 --cache-stats --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki sync --include-tests go --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --initialize-surfaces flows,dependencies --flow-category http --exclude-tests --dry-run
@@ -398,8 +422,10 @@ persistent inventory cache as lint when a git directory is available. Use
 `--no-cache`, `--rebuild-cache`, `--cache-dir PATH`, and `--cache-stats` to
 control or inspect inventory cache behavior. Use `--helper-cache-dir PATH` to
 point Go/Rust/Haskell extraction at prepared helpers in a separate cache. Use
-`--jobs N` or `--jobs auto` to opt into parallel extraction for built-in
-languages and plugin extractors whose manifests set `"parallel_safe": true`.
+The interactive default is `--jobs 1`. Use `--jobs N` or `--jobs auto` to opt
+into parallel extraction for built-in languages and plugin extractors whose
+manifests set `"parallel_safe": true`; reserve `auto` for an isolated terminal
+or controlled CI runner with known capacity.
 Sync repairs
 manifests with invalid source hashes without touching pages, and stops unusually
 broad diffs unless `--force` is used.
@@ -592,7 +618,7 @@ llm-wiki lint --profile --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --cache-stats --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki lint --include-tests go --wiki-dir docs/llm_wiki --src-dir .
-llm-wiki lint --jobs auto --wiki-dir docs/llm_wiki --src-dir .
+llm-wiki lint --jobs 1 --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --wiki-dir docs/llm_wiki --src-dir /path/to/repo --allow-external-src
 ```
 
@@ -601,6 +627,27 @@ Strict mode also requires the core wiki structure and a fresh sync manifest.
 to stdout containing the normal lint report, diagnostics, and phase timings.
 The JSON contract is preserved for extractor failures as well; lint still exits
 nonzero, but stdout remains machine-readable.
+`lint --profile` and `ci-check --format json` additionally include this shape:
+
+```json
+{
+  "execution": {
+    "extractor_jobs": {
+      "requested_jobs": "auto",
+      "resolved_jobs": 20,
+      "eligible_parallel_plans": 2,
+      "effective_workers": 2,
+      "parallel_plan_ids": ["python", "typescript"],
+      "sequential_plan_ids": [],
+      "cache_elided_plan_ids": []
+    }
+  }
+}
+```
+
+This metadata is additive only in those two JSON modes. Default lint report
+serialization, MCP lint responses, CI text/Markdown output, sync state and
+manifests, and the `llm-wiki-context/v1` protocol stay unchanged.
 Lint uses a persistent deep-inventory cache by default when a git directory is
 available, storing `.git/llm-wiki-inventory-cache.json`. Override the cache
 directory with `LLM_WIKI_CACHE_DIR` or `--cache-dir PATH`; the CLI flag wins for
@@ -612,8 +659,9 @@ Cache corruption or invalid fingerprints fall back to a full extraction without
 reducing lint coverage. With `--profile --cache-stats`, the JSON payload includes a top-level
 `cache` object. Use `--jobs N` or `--jobs auto` to opt into parallel extraction
 for built-in languages and plugin extractors whose manifests set
-`"parallel_safe": true`; the default is `--jobs 1`. Plugin extractors without
-that opt-in remain sequential.
+`"parallel_safe": true`; the default and recommended interactive setting is
+`--jobs 1`. Reserve `auto` for an isolated terminal or controlled CI runner
+with known capacity. Plugin extractors without that opt-in remain sequential.
 Use `--include-tests go` when a wiki intentionally documents Go `_test.go`
 files; omit it to lint against the default production-source inventory.
 For trusted source trees outside the runner workspace, pass
@@ -677,6 +725,7 @@ For CI:
 
 ```bash
 llm-wiki ci-check --src-dir . --wiki-dir docs/llm_wiki
+# Capacity-reserved CI only; shared or unknown-capacity runners should use jobs 1.
 llm-wiki ci-check --jobs auto --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --helper-cache-dir .cache/llm-wiki-helpers --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --include-tests go --src-dir . --wiki-dir docs/llm_wiki
@@ -710,6 +759,13 @@ llm-wiki context --budget 12000 --format json --focus all --output context.json
 `--focus changed` is the default. Changed files get full detail, one-hop import
 neighbors get slim detail, and remaining files get names only.
 
+For broad repository-wide work, run one serialized
+`llm-wiki context --budget 8000 --focus changed --read-only`, then read only the
+source and wiki pages it selects. For a narrow task with supplied files or a
+supplied diff, skip the full context scan and use the wiki index only for
+navigation. The budget and focus bound emitted output after a full deep
+inventory; they do not make the scan computationally cheap.
+
 External tools can use the `llm-wiki-context/v1` JSON request protocol:
 
 ```bash

{agent_wiki_cli-1.3.1 → agent_wiki_cli-1.4.0}/README.md

@@ -270,6 +270,30 @@ llm-wiki install-hook --force
 
 ## Command Reference
 
+### Resource-aware execution
+
+In an interactive IDE or whenever host capacity is unknown, run one heavy gate
+at a time. Heavy gates include `context`, full tests, coverage, builds, browser
+suites, `sync`, `lint`, and `ci-check`. The supervising agent owns that
+schedule; subagents may inspect bounded files and diffs, but should not launch
+heavy gates unless explicitly assigned.
+
+Use `--jobs 1` for interactive source scans. `--jobs auto` remains an uncapped
+opt-in for an isolated terminal or a controlled CI runner with reserved
+capacity; do not combine it with nested heavy-gate fan-out. If ENOSPC, inotify,
+file-descriptor, severe swapping, or editor-responsiveness failures occur, stop
+launching work and do not retry the same burst. Recover capacity first, then
+attempt at most one manual retry with `--jobs 1`; unfinished gates remain
+inconclusive. Watcher-limit symptoms are host/IDE resource evidence, not proof
+that `llm-wiki` leaked a watcher.
+
+Before extraction, `sync`, `lint`, `ci-check`, and `context` write one flushed
+plan line to stderr without contaminating stdout, for example:
+
+```text
+Extractor plan: requested=auto resolved=20 eligible_parallel=2 effective_workers=2 parallel=python,typescript sequential=- cache_elided=-
+```
+
 ### `init`
 
 Scaffold the wiki structure and agent constraint file.
@@ -352,7 +376,7 @@ manifest.
 
 ```bash
 llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki
-llm-wiki sync --jobs auto --cache-stats --src-dir . --wiki-dir docs/llm_wiki
+llm-wiki sync --jobs 1 --cache-stats --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki sync --include-tests go --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --initialize-surfaces flows,dependencies --flow-category http --exclude-tests --dry-run
@@ -367,8 +391,10 @@ persistent inventory cache as lint when a git directory is available. Use
 `--no-cache`, `--rebuild-cache`, `--cache-dir PATH`, and `--cache-stats` to
 control or inspect inventory cache behavior. Use `--helper-cache-dir PATH` to
 point Go/Rust/Haskell extraction at prepared helpers in a separate cache. Use
-`--jobs N` or `--jobs auto` to opt into parallel extraction for built-in
-languages and plugin extractors whose manifests set `"parallel_safe": true`.
+The interactive default is `--jobs 1`. Use `--jobs N` or `--jobs auto` to opt
+into parallel extraction for built-in languages and plugin extractors whose
+manifests set `"parallel_safe": true`; reserve `auto` for an isolated terminal
+or controlled CI runner with known capacity.
 Sync repairs
 manifests with invalid source hashes without touching pages, and stops unusually
 broad diffs unless `--force` is used.
@@ -561,7 +587,7 @@ llm-wiki lint --profile --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --cache-stats --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki lint --include-tests go --wiki-dir docs/llm_wiki --src-dir .
-llm-wiki lint --jobs auto --wiki-dir docs/llm_wiki --src-dir .
+llm-wiki lint --jobs 1 --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --wiki-dir docs/llm_wiki --src-dir /path/to/repo --allow-external-src
 ```
 
@@ -570,6 +596,27 @@ Strict mode also requires the core wiki structure and a fresh sync manifest.
 to stdout containing the normal lint report, diagnostics, and phase timings.
 The JSON contract is preserved for extractor failures as well; lint still exits
 nonzero, but stdout remains machine-readable.
+`lint --profile` and `ci-check --format json` additionally include this shape:
+
+```json
+{
+  "execution": {
+    "extractor_jobs": {
+      "requested_jobs": "auto",
+      "resolved_jobs": 20,
+      "eligible_parallel_plans": 2,
+      "effective_workers": 2,
+      "parallel_plan_ids": ["python", "typescript"],
+      "sequential_plan_ids": [],
+      "cache_elided_plan_ids": []
+    }
+  }
+}
+```
+
+This metadata is additive only in those two JSON modes. Default lint report
+serialization, MCP lint responses, CI text/Markdown output, sync state and
+manifests, and the `llm-wiki-context/v1` protocol stay unchanged.
 Lint uses a persistent deep-inventory cache by default when a git directory is
 available, storing `.git/llm-wiki-inventory-cache.json`. Override the cache
 directory with `LLM_WIKI_CACHE_DIR` or `--cache-dir PATH`; the CLI flag wins for
@@ -581,8 +628,9 @@ Cache corruption or invalid fingerprints fall back to a full extraction without
 reducing lint coverage. With `--profile --cache-stats`, the JSON payload includes a top-level
 `cache` object. Use `--jobs N` or `--jobs auto` to opt into parallel extraction
 for built-in languages and plugin extractors whose manifests set
-`"parallel_safe": true`; the default is `--jobs 1`. Plugin extractors without
-that opt-in remain sequential.
+`"parallel_safe": true`; the default and recommended interactive setting is
+`--jobs 1`. Reserve `auto` for an isolated terminal or controlled CI runner
+with known capacity. Plugin extractors without that opt-in remain sequential.
 Use `--include-tests go` when a wiki intentionally documents Go `_test.go`
 files; omit it to lint against the default production-source inventory.
 For trusted source trees outside the runner workspace, pass
@@ -646,6 +694,7 @@ For CI:
 
 ```bash
 llm-wiki ci-check --src-dir . --wiki-dir docs/llm_wiki
+# Capacity-reserved CI only; shared or unknown-capacity runners should use jobs 1.
 llm-wiki ci-check --jobs auto --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --helper-cache-dir .cache/llm-wiki-helpers --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --include-tests go --src-dir . --wiki-dir docs/llm_wiki
@@ -679,6 +728,13 @@ llm-wiki context --budget 12000 --format json --focus all --output context.json
 `--focus changed` is the default. Changed files get full detail, one-hop import
 neighbors get slim detail, and remaining files get names only.
 
+For broad repository-wide work, run one serialized
+`llm-wiki context --budget 8000 --focus changed --read-only`, then read only the
+source and wiki pages it selects. For a narrow task with supplied files or a
+supplied diff, skip the full context scan and use the wiki index only for
+navigation. The budget and focus bound emitted output after a full deep
+inventory; they do not make the scan computationally cheap.
+
 External tools can use the `llm-wiki-context/v1` JSON request protocol:
 
 ```bash

{agent_wiki_cli-1.3.1 → agent_wiki_cli-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-wiki-cli"
-version = "1.3.1"
+version = "1.4.0"
 description = "CLI tool to maintain hybrid LLM Wikis for multi-language projects."
 readme = "README.md"
 license = {text = "MIT"}

{agent_wiki_cli-1.3.1 → agent_wiki_cli-1.4.0/src/agent_wiki_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 1.3.1
+Version: 1.4.0
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License: MIT
@@ -301,6 +301,30 @@ llm-wiki install-hook --force
 
 ## Command Reference
 
+### Resource-aware execution
+
+In an interactive IDE or whenever host capacity is unknown, run one heavy gate
+at a time. Heavy gates include `context`, full tests, coverage, builds, browser
+suites, `sync`, `lint`, and `ci-check`. The supervising agent owns that
+schedule; subagents may inspect bounded files and diffs, but should not launch
+heavy gates unless explicitly assigned.
+
+Use `--jobs 1` for interactive source scans. `--jobs auto` remains an uncapped
+opt-in for an isolated terminal or a controlled CI runner with reserved
+capacity; do not combine it with nested heavy-gate fan-out. If ENOSPC, inotify,
+file-descriptor, severe swapping, or editor-responsiveness failures occur, stop
+launching work and do not retry the same burst. Recover capacity first, then
+attempt at most one manual retry with `--jobs 1`; unfinished gates remain
+inconclusive. Watcher-limit symptoms are host/IDE resource evidence, not proof
+that `llm-wiki` leaked a watcher.
+
+Before extraction, `sync`, `lint`, `ci-check`, and `context` write one flushed
+plan line to stderr without contaminating stdout, for example:
+
+```text
+Extractor plan: requested=auto resolved=20 eligible_parallel=2 effective_workers=2 parallel=python,typescript sequential=- cache_elided=-
+```
+
 ### `init`
 
 Scaffold the wiki structure and agent constraint file.
@@ -383,7 +407,7 @@ manifest.
 
 ```bash
 llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki
-llm-wiki sync --jobs auto --cache-stats --src-dir . --wiki-dir docs/llm_wiki
+llm-wiki sync --jobs 1 --cache-stats --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki sync --include-tests go --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --initialize-surfaces flows,dependencies --flow-category http --exclude-tests --dry-run
@@ -398,8 +422,10 @@ persistent inventory cache as lint when a git directory is available. Use
 `--no-cache`, `--rebuild-cache`, `--cache-dir PATH`, and `--cache-stats` to
 control or inspect inventory cache behavior. Use `--helper-cache-dir PATH` to
 point Go/Rust/Haskell extraction at prepared helpers in a separate cache. Use
-`--jobs N` or `--jobs auto` to opt into parallel extraction for built-in
-languages and plugin extractors whose manifests set `"parallel_safe": true`.
+The interactive default is `--jobs 1`. Use `--jobs N` or `--jobs auto` to opt
+into parallel extraction for built-in languages and plugin extractors whose
+manifests set `"parallel_safe": true`; reserve `auto` for an isolated terminal
+or controlled CI runner with known capacity.
 Sync repairs
 manifests with invalid source hashes without touching pages, and stops unusually
 broad diffs unless `--force` is used.
@@ -592,7 +618,7 @@ llm-wiki lint --profile --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --cache-stats --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki lint --include-tests go --wiki-dir docs/llm_wiki --src-dir .
-llm-wiki lint --jobs auto --wiki-dir docs/llm_wiki --src-dir .
+llm-wiki lint --jobs 1 --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --wiki-dir docs/llm_wiki --src-dir /path/to/repo --allow-external-src
 ```
 
@@ -601,6 +627,27 @@ Strict mode also requires the core wiki structure and a fresh sync manifest.
 to stdout containing the normal lint report, diagnostics, and phase timings.
 The JSON contract is preserved for extractor failures as well; lint still exits
 nonzero, but stdout remains machine-readable.
+`lint --profile` and `ci-check --format json` additionally include this shape:
+
+```json
+{
+  "execution": {
+    "extractor_jobs": {
+      "requested_jobs": "auto",
+      "resolved_jobs": 20,
+      "eligible_parallel_plans": 2,
+      "effective_workers": 2,
+      "parallel_plan_ids": ["python", "typescript"],
+      "sequential_plan_ids": [],
+      "cache_elided_plan_ids": []
+    }
+  }
+}
+```
+
+This metadata is additive only in those two JSON modes. Default lint report
+serialization, MCP lint responses, CI text/Markdown output, sync state and
+manifests, and the `llm-wiki-context/v1` protocol stay unchanged.
 Lint uses a persistent deep-inventory cache by default when a git directory is
 available, storing `.git/llm-wiki-inventory-cache.json`. Override the cache
 directory with `LLM_WIKI_CACHE_DIR` or `--cache-dir PATH`; the CLI flag wins for
@@ -612,8 +659,9 @@ Cache corruption or invalid fingerprints fall back to a full extraction without
 reducing lint coverage. With `--profile --cache-stats`, the JSON payload includes a top-level
 `cache` object. Use `--jobs N` or `--jobs auto` to opt into parallel extraction
 for built-in languages and plugin extractors whose manifests set
-`"parallel_safe": true`; the default is `--jobs 1`. Plugin extractors without
-that opt-in remain sequential.
+`"parallel_safe": true`; the default and recommended interactive setting is
+`--jobs 1`. Reserve `auto` for an isolated terminal or controlled CI runner
+with known capacity. Plugin extractors without that opt-in remain sequential.
 Use `--include-tests go` when a wiki intentionally documents Go `_test.go`
 files; omit it to lint against the default production-source inventory.
 For trusted source trees outside the runner workspace, pass
@@ -677,6 +725,7 @@ For CI:
 
 ```bash
 llm-wiki ci-check --src-dir . --wiki-dir docs/llm_wiki
+# Capacity-reserved CI only; shared or unknown-capacity runners should use jobs 1.
 llm-wiki ci-check --jobs auto --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --helper-cache-dir .cache/llm-wiki-helpers --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --include-tests go --src-dir . --wiki-dir docs/llm_wiki
@@ -710,6 +759,13 @@ llm-wiki context --budget 12000 --format json --focus all --output context.json
 `--focus changed` is the default. Changed files get full detail, one-hop import
 neighbors get slim detail, and remaining files get names only.
 
+For broad repository-wide work, run one serialized
+`llm-wiki context --budget 8000 --focus changed --read-only`, then read only the
+source and wiki pages it selects. For a narrow task with supplied files or a
+supplied diff, skip the full context scan and use the wiki index only for
+navigation. The budget and focus bound emitted output after a full deep
+inventory; they do not make the scan computationally cheap.
+
 External tools can use the `llm-wiki-context/v1` JSON request protocol:
 
 ```bash

{agent_wiki_cli-1.3.1 → agent_wiki_cli-1.4.0}/src/agent_wiki_cli.egg-info/SOURCES.txt

@@ -75,6 +75,7 @@ src/llm_wiki_cli/services/dependencies.py
 src/llm_wiki_cli/services/diagrams.py
 src/llm_wiki_cli/services/documentation_queries.py
 src/llm_wiki_cli/services/entrypoints.py
+src/llm_wiki_cli/services/extraction_jobs.py
 src/llm_wiki_cli/services/extractor_helpers.py
 src/llm_wiki_cli/services/imports.py
 src/llm_wiki_cli/services/infrastructure_inventory.py
@@ -90,6 +91,7 @@ src/llm_wiki_cli/services/paths.py
 src/llm_wiki_cli/services/plugin_samples.py
 src/llm_wiki_cli/services/plugins.py
 src/llm_wiki_cli/services/relationships.py
+src/llm_wiki_cli/services/resource_diagnostics.py
 src/llm_wiki_cli/services/schema.py
 src/llm_wiki_cli/services/secure_file.py
 src/llm_wiki_cli/services/site_export.py
@@ -181,6 +183,7 @@ tests/test_phase4_quality.py
 tests/test_plugins.py
 tests/test_relationships.py
 tests/test_release.py
+tests/test_resource_diagnostics.py
 tests/test_rust_extract.py
 tests/test_schema.py
 tests/test_secure_file.py

{agent_wiki_cli-1.3.1 → agent_wiki_cli-1.4.0}/src/llm_wiki_cli/cli.py

@@ -31,6 +31,8 @@ from .commands import (
 )
 from .config import AGENT_CHOICES, DEFAULT_WIKI_DIR, PathValidationError
 from .services.contracts import BOOTSTRAP_SKIP_DATA_FLOW_FLAG
+from .services.extraction_jobs import ExtractionJobsAction
+from .services.resource_diagnostics import resource_failure_hint
 from . import __version__
 
 
@@ -41,20 +43,6 @@ def _positive_int(value: str) -> int:
     return parsed
 
 
-def _jobs_value(value: str) -> int:
-    if value == "auto":
-        return max(1, os.cpu_count() or 1)
-    try:
-        parsed = int(value)
-    except ValueError as exc:
-        raise argparse.ArgumentTypeError(
-            "must be a positive integer or 'auto'"
-        ) from exc
-    if parsed < 1:
-        raise argparse.ArgumentTypeError("must be greater than zero")
-    return parsed
-
-
 def _surface_values(value: str) -> tuple[str, ...]:
     values = tuple(part.strip().lower() for part in value.split(",") if part.strip())
     if not values:
@@ -91,6 +79,20 @@ def _add_include_tests_argument(parser):
     )
 
 
+def _add_jobs_argument(parser):
+    parser.set_defaults(requested_jobs=1)
+    parser.add_argument(
+        "--jobs",
+        action=ExtractionJobsAction,
+        default=1,
+        metavar="JOBS",
+        help=(
+            "Parallel extractor jobs for built-ins and opted-in plugins: "
+            "positive integer or 'auto' (default: 1)"
+        ),
+    )
+
+
 _COMMAND_MODULES = {
     "init": init_cmd,
     "extract": extract_cmd,
@@ -328,13 +330,7 @@ def _add_lint_command(subparsers):
     )
     _add_helper_cache_argument(lint_parser)
     _add_include_tests_argument(lint_parser)
-    lint_parser.add_argument(
-        "--jobs",
-        type=_jobs_value,
-        default=1,
-        metavar="JOBS",
-        help="Parallel extractor jobs for built-ins and opted-in plugins: positive integer or 'auto' (default: 1)",
-    )
+    _add_jobs_argument(lint_parser)
 
 
 def _add_prepare_extractors_command(subparsers):
@@ -392,13 +388,7 @@ def _add_ci_check_command(subparsers):
     )
     _add_helper_cache_argument(ci_parser)
     _add_include_tests_argument(ci_parser)
-    ci_parser.add_argument(
-        "--jobs",
-        type=_jobs_value,
-        default=1,
-        metavar="JOBS",
-        help="Parallel extractor jobs for built-ins and opted-in plugins: positive integer or 'auto' (default: 1)",
-    )
+    _add_jobs_argument(ci_parser)
 
 
 def _add_install_hook_command(subparsers):
@@ -1220,13 +1210,7 @@ def _add_sync_command(subparsers):
     )
     _add_helper_cache_argument(sync_parser)
     _add_include_tests_argument(sync_parser)
-    sync_parser.add_argument(
-        "--jobs",
-        type=_jobs_value,
-        default=1,
-        metavar="JOBS",
-        help="Parallel extractor jobs for built-ins and opted-in plugins: positive integer or 'auto' (default: 1)",
-    )
+    _add_jobs_argument(sync_parser)
     sync_parser.add_argument(
         "--force",
         action="store_true",
@@ -1394,6 +1378,9 @@ def main():
         if os.environ.get("LLM_WIKI_DEBUG"):
             raise
         print(f"Error: {exc}", file=sys.stderr)
+        hint = resource_failure_hint(exc)
+        if hint is not None:
+            print(f"Resource guidance: {hint}", file=sys.stderr)
         sys.exit(1)
 
 

{agent_wiki_cli-1.3.1 → agent_wiki_cli-1.4.0}/src/llm_wiki_cli/commands/ci_check_cmd.py

@@ -7,6 +7,10 @@ from pathlib import Path
 
 from ..config import DEFAULT_WIKI_DIR, validate_path, validate_source_root
 from ..services.inventory_cache import InventoryCacheOptions
+from ..services.extraction_jobs import (
+    extraction_job_request_from_args,
+    print_extraction_job_plan,
+)
 from ..services.metrics import record_validation_event
 from .lint_cmd import build_report, render_markdown, render_text, report_to_dict
 
@@ -15,7 +19,14 @@ DEFAULT_REPORT = ".git/llm-wiki-ci-report.md"
 
 def _render_console(report, output_format: str) -> str:
     if output_format == "json":
-        return json.dumps(report_to_dict(report), indent=2, sort_keys=True) + "\n"
+        return (
+            json.dumps(
+                report_to_dict(report, include_execution=True),
+                indent=2,
+                sort_keys=True,
+            )
+            + "\n"
+        )
     if output_format == "markdown":
         return render_markdown(report)
     return render_text(report)
@@ -38,6 +49,7 @@ def run(args) -> None:
     validate_path(wiki_dir, "--wiki-dir")
 
     started = time.monotonic()
+    job_request = extraction_job_request_from_args(args)
     report = build_report(
         wiki_dir,
         src_dir,
@@ -46,6 +58,8 @@ def run(args) -> None:
         parallel_jobs=getattr(args, "jobs", 1),
         helper_cache_dir=helper_cache_dir,
         include_tests=include_tests,
+        job_request=job_request,
+        plan_reporter=print_extraction_job_plan,
     )
     duration_ms = int((time.monotonic() - started) * 1000)
 

{agent_wiki_cli-1.3.1 → agent_wiki_cli-1.4.0}/src/llm_wiki_cli/commands/context_cmd.py

@@ -16,6 +16,7 @@ Usage::
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from fnmatch import fnmatch
 import json
 import sys
@@ -43,6 +44,11 @@ from ..services.documentation_queries import (
     DocumentationGraphQueryService,
     DocumentationQueryError,
 )
+from ..services.extraction_jobs import (
+    ExtractionJobPlan,
+    ExtractionJobRequest,
+    print_extraction_job_plan,
+)
 from ..services.io import write_text_output
 from ..services.wiki_surface_index import build_surface_index
 
@@ -73,9 +79,21 @@ def _extractor_failure_message(inventory_result) -> str:
     return "; ".join(details) or "Source extraction failed."
 
 
-def get_inventory(src_dir: str, *, deep: bool = False) -> dict:
+def get_inventory(
+    src_dir: str,
+    *,
+    deep: bool = False,
+    job_request: ExtractionJobRequest | None = None,
+    plan_reporter: Callable[[ExtractionJobPlan], None] | None = None,
+) -> dict:
     """Context-local inventory helper kept patchable for protocol tests."""
-    inventory_result = get_inventory_result(src_dir, deep=deep)
+    inventory_result = get_inventory_result(
+        src_dir,
+        deep=deep,
+        parallel_jobs=job_request.resolved_jobs if job_request is not None else 1,
+        job_request=job_request,
+        plan_reporter=plan_reporter,
+    )
     if inventory_result.failed:
         raise ProtocolRequestError(
             _extractor_failure_message(inventory_result), "src_dir"
@@ -790,6 +808,8 @@ def _build_context(
     allow_external_src: bool = False,
     read_only: bool = False,
     wiki_dir: str = DEFAULT_WIKI_DIR,
+    job_request: ExtractionJobRequest | None = None,
+    plan_reporter: Callable[[ExtractionJobPlan], None] | None = None,
 ) -> tuple[dict, list[str]]:
     """Build a context payload and return ``(payload, warnings)``."""
     src_root = validate_source_root(
@@ -798,7 +818,12 @@ def _build_context(
         allow_external=allow_external_src,
     )
 
-    raw_inventory = get_inventory(str(src_root), deep=True)
+    raw_inventory = get_inventory(
+        str(src_root),
+        deep=True,
+        job_request=job_request,
+        plan_reporter=plan_reporter,
+    )
     filters = filters or {}
     inventory = _apply_protocol_filters(raw_inventory, filters)
     warnings: list[str] = []
@@ -899,6 +924,8 @@ def _run_protocol(args) -> None:
             allow_external_src=getattr(args, "allow_external_src", False),
             read_only=getattr(args, "read_only", False),
             wiki_dir=getattr(args, "wiki_dir", DEFAULT_WIKI_DIR),
+            job_request=ExtractionJobRequest.resolved(1),
+            plan_reporter=print_extraction_job_plan,
         )
     except ProtocolRequestError as exc:
         _emit_protocol_error(exc)
@@ -947,6 +974,8 @@ def run(args) -> None:
             emit_warnings=True,
             allow_external_src=allow_external_src,
             read_only=read_only,
+            job_request=ExtractionJobRequest.resolved(1),
+            plan_reporter=print_extraction_job_plan,
         )
     except ProtocolRequestError as exc:
         print(f"Error: {exc}", file=sys.stderr)