sourcecode 4.9.1__tar.gz → 4.10.0__tar.gz

{sourcecode-4.9.1 → sourcecode-4.10.0}/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## [Unreleased]
 
+## [4.10.0] — 2026-08-05
+
+### Fixed
+
+- **Canonical endpoint projection rejects parser-corrupt Java handler names.**
+  Reserved Java keywords such as `if` can no longer reach CIR/risk as synthetic
+  handler symbols.
+- **`DEAD-001` reports commented Java security annotations.** Java comments that
+  contain Spring/Jakarta/custom security annotations are now treated as disabled
+  controls, while active annotations stay out of dead-code findings.
+- **`SEC-007` reports JavaMelody descriptor credentials.** `authorized-users`
+  values in deployment descriptors are detected and redacted even when they are
+  not written as `{SHA-*}` digest literals.
+- **`audit-report` can reuse existing risk evidence.** `--from-risk risk.json`
+  packages a previous `ask risk` payload instead of recomputing repo-wide risk.
+- **Long analysis observability improved.** `ASK_PROGRESS=1` enables non-TTY
+  heartbeat lines, long commands write durable `.ask/runs` records, and file
+  outputs are written atomically.
+- **Large-repo CI budgets are explicit.** `ASK_MAX_ANALYSIS_SECONDS` can fail a
+  repo-wide/deep command before work starts when the configured budget is below
+  the command's safe floor.
+
+### Documentation
+
+- README, user guide and root `ask --help` now distinguish per-symbol,
+  inventory and repo-wide/deep command costs instead of treating cache
+  benchmarks as universal runtime promises.
+
 ## [4.9.1] — 2026-08-04
 
 ### Added

{sourcecode-4.9.1 → sourcecode-4.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.9.1
+Version: 4.10.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.9.1-blue)
+![Version](https://img.shields.io/badge/version-4.10.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -54,9 +54,9 @@ Description-Content-Type: text/markdown
 
 ## The problem
 
-Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. For a large Java or TypeScript monolith, that means 5–15 seconds per invocation. Multiply by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
+Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. On small and mid-sized repos that cost is seconds; on large Java/Spring monoliths, repo-wide semantic composition can be minutes. Multiply that by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
 
-ASK Engine solves this with a persistent structural cache keyed on file content hashes. After the first scan, every subsequent invocation returns pre-built context in milliseconds. The repo doesn't change? The cache doesn't expire.
+ASK Engine solves this with a persistent structural cache keyed on file content hashes. After the first scan, later invocations reuse pre-built context whenever their command can consume the warmed layers. The repo doesn't change? The cache doesn't expire.
 
 **The cache is not a performance optimization. It is what makes ASK Engine usable as infrastructure rather than a one-off tool.**
 
@@ -69,9 +69,11 @@ ASK Engine solves this with a persistent structural cache keyed on file content
 | Keycloak | 7,885 Java files | 10.5s | 0.6s | **~17x** |
 | BroadleafCommerce | 2,985 Java files | 2.7s | 0.3s | **~9x** |
 
-Cache keyed on content hashes — invalidated only when source changes. On repeated agent sessions against the same codebase, nearly every invocation is a cache hit.
+These numbers are cache-layer benchmarks, not a promise for every command. Per-symbol queries and compact context benefit most. Inventory commands scale with file count. Repo-wide/deep compositions such as `risk`, `audit-report` and large `spring-audit` runs can take minutes on multi-thousand-endpoint repositories and belong in a supervised or nightly job unless CI sets an explicit budget.
 
-At 0.3s per call, ASK Engine becomes **constant infrastructure** inside agent loops — call it before every edit, every PR review, every test run, without batching or caching manually.
+With the right command class, ASK Engine becomes **constant infrastructure** inside agent loops — call the fast/context surfaces before edits and reserve deep compositions for the points where their evidence is worth the runtime.
+
+**Large-repo controls.** Set `ASK_PROGRESS=1` to get line heartbeats in non-TTY supervised runs. Set `ASK_MAX_ANALYSIS_SECONDS=<seconds>` to fail before starting a repo-wide/deep command whose configured budget is below its safe floor. Use `ask audit-report --from-risk risk.json` to package an existing risk run instead of recomputing it.
 
 **What a warm actually covers.** `ask cache warm` runs the compact analysis: it rebuilds the
 shared structural layers (L1/L2 + the Repository Intelligence Snapshot + the shared Canonical
@@ -97,7 +99,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.9.1 — and, on a build that has aged,
+ask version                    # ask 4.10.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.9.1 → sourcecode-4.10.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.9.1-blue)
+![Version](https://img.shields.io/badge/version-4.10.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -16,9 +16,9 @@
 
 ## The problem
 
-Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. For a large Java or TypeScript monolith, that means 5–15 seconds per invocation. Multiply by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
+Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. On small and mid-sized repos that cost is seconds; on large Java/Spring monoliths, repo-wide semantic composition can be minutes. Multiply that by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
 
-ASK Engine solves this with a persistent structural cache keyed on file content hashes. After the first scan, every subsequent invocation returns pre-built context in milliseconds. The repo doesn't change? The cache doesn't expire.
+ASK Engine solves this with a persistent structural cache keyed on file content hashes. After the first scan, later invocations reuse pre-built context whenever their command can consume the warmed layers. The repo doesn't change? The cache doesn't expire.
 
 **The cache is not a performance optimization. It is what makes ASK Engine usable as infrastructure rather than a one-off tool.**
 
@@ -31,9 +31,11 @@ ASK Engine solves this with a persistent structural cache keyed on file content
 | Keycloak | 7,885 Java files | 10.5s | 0.6s | **~17x** |
 | BroadleafCommerce | 2,985 Java files | 2.7s | 0.3s | **~9x** |
 
-Cache keyed on content hashes — invalidated only when source changes. On repeated agent sessions against the same codebase, nearly every invocation is a cache hit.
+These numbers are cache-layer benchmarks, not a promise for every command. Per-symbol queries and compact context benefit most. Inventory commands scale with file count. Repo-wide/deep compositions such as `risk`, `audit-report` and large `spring-audit` runs can take minutes on multi-thousand-endpoint repositories and belong in a supervised or nightly job unless CI sets an explicit budget.
 
-At 0.3s per call, ASK Engine becomes **constant infrastructure** inside agent loops — call it before every edit, every PR review, every test run, without batching or caching manually.
+With the right command class, ASK Engine becomes **constant infrastructure** inside agent loops — call the fast/context surfaces before edits and reserve deep compositions for the points where their evidence is worth the runtime.
+
+**Large-repo controls.** Set `ASK_PROGRESS=1` to get line heartbeats in non-TTY supervised runs. Set `ASK_MAX_ANALYSIS_SECONDS=<seconds>` to fail before starting a repo-wide/deep command whose configured budget is below its safe floor. Use `ask audit-report --from-risk risk.json` to package an existing risk run instead of recomputing it.
 
 **What a warm actually covers.** `ask cache warm` runs the compact analysis: it rebuilds the
 shared structural layers (L1/L2 + the Repository Intelligence Snapshot + the shared Canonical
@@ -59,7 +61,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.9.1 — and, on a build that has aged,
+ask version                    # ask 4.10.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.9.1 → sourcecode-4.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "4.9.1"
+version = "4.10.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-4.9.1 → sourcecode-4.10.0}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "4.9.1"
+__version__ = "4.10.0"

{sourcecode-4.9.1 → sourcecode-4.10.0}/src/sourcecode/audit_report.py

@@ -39,13 +39,19 @@ def build_audit_report(
     profiles: Optional[set[str]] = None,
     sign_key: Optional[bytes] = None,
     risk_limit: int = 10,
+    risk_payload: Optional[dict[str, Any]] = None,
 ) -> dict[str, Any]:
     """Build the buyer-readable audit bundle from existing command payloads."""
     from sourcecode.posture import build_posture
-    from sourcecode.risk import build_risk
 
     root = Path(root).resolve()
-    risk = build_risk(root, limit=risk_limit, min_band="low", profiles=profiles)
+    if risk_payload is None:
+        from sourcecode.risk import build_risk
+        risk = build_risk(root, limit=risk_limit, min_band="low", profiles=profiles)
+        risk_source = "computed"
+    else:
+        risk = risk_payload
+        risk_source = "from-risk"
     posture = build_posture(root, profiles or set())
     top_risks = risk.get("risks", [])[:risk_limit]
     access = ((posture.get("endpoints") or {}).get("effective_access") or {})
@@ -58,6 +64,7 @@ def build_audit_report(
         **({"profile_set": sorted(profiles)} if profiles else {}),
         "summary": {
             "risk_model": risk.get("model"),
+            "risk_source": risk_source,
             "total_defects": risk.get("total_defects"),
             "total_findings": risk.get("total_findings"),
             "risk_bands": risk.get("by_band", {}),
@@ -86,6 +93,7 @@ def build_audit_report(
         inputs={
             "profiles": sorted(profiles) if profiles else None,
             "risk_limit": risk_limit,
+            "risk_source": risk_source,
             "signed": bool(sign_key),
         },
     )

{sourcecode-4.9.1 → sourcecode-4.10.0}/src/sourcecode/cache_model.py

@@ -144,6 +144,12 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "repository side, so what it buys is what it buys `risk`.",
                  "not measured on the battery yet — bounded by the `risk` composition, plus "
                  "reading one JSON file"),
+    CommandCache("audit-report", ("cir", "parse"), "shared", False,
+                 "Packages `risk` and `posture` evidence. A warm helps the repository side; "
+                 "`--from-risk risk.json` skips risk recomputation entirely and only builds "
+                 "the posture/report projection.",
+                 "not measured on the battery yet — bounded by `risk` + `posture`, or by "
+                 "`posture` when `--from-risk` is supplied"),
     CommandCache("migrate-recipe", ("parse",), "shared", False,
                  "Runs the same scan as `migrate-check` and projects its findings into an "
                  "OpenRewrite recipe, so it buys exactly what a warm buys `migrate-check`: "

{sourcecode-4.9.1 → sourcecode-4.10.0}/src/sourcecode/canonical_ir.py

@@ -43,6 +43,23 @@ _REVERSE_EXCLUDE: frozenset[str] = frozenset({"annotated_with", "mapped_to"})
 # the CIR endpoint count reconciles with the `endpoints` command). See BUG #7.
 _FQN_PATH_RE: re.Pattern = re.compile(r"/(org|com|net|io|edu)\.[a-z][a-z0-9]*\.[a-zA-Z]")
 
+_JAVA_RESERVED_HANDLER_NAMES: frozenset[str] = frozenset({
+    "if", "else", "for", "while", "do", "switch", "case", "break", "continue",
+    "return", "new", "throw", "try", "catch", "finally", "instanceof",
+    "this", "super", "void", "class", "interface", "enum", "extends", "implements",
+    "import", "package", "static", "final", "abstract", "synchronized", "native",
+    "true", "false", "null",
+})
+
+
+def _route_has_reserved_handler(route: dict) -> bool:
+    """Reject parser-corrupt endpoint symbols such as ``pkg.Controller#if``."""
+    symbol = str(route.get("symbol") or "")
+    if "#" not in symbol:
+        return False
+    handler = symbol.rsplit("#", 1)[1].split("(", 1)[0].strip()
+    return handler in _JAVA_RESERVED_HANDLER_NAMES
+
 
 # ---------------------------------------------------------------------------
 # CanonicalSecurity
@@ -438,6 +455,8 @@ def ir_dict_to_canonical(
     for r in route_surface:
         if r.get("scope") == "test_util":
             continue
+        if _route_has_reserved_handler(r):
+            continue
         if _FQN_PATH_RE.search(r.get("path", "") or ""):
             continue
         ep = _route_to_canonical_endpoint(r)

{sourcecode-4.9.1 → sourcecode-4.10.0}/src/sourcecode/cli.py

@@ -338,8 +338,10 @@ def _build_help_text() -> str:
 Deterministic Java/Spring semantics and reusable structural context for AI coding agents.
 
 Cache warms on first scan; later calls reuse pre-built context instead of rescanning.
-Scan and warm time scale with repo size — small repos in seconds, large repos (thousands
-of files) in minutes. Semantic analysis itself is sub-second; repo indexing dominates.
+Performance depends on command class and repo size: per-symbol queries are the fast path,
+inventory commands scale with files, and repo-wide/deep compositions can take
+minutes on multi-thousand-endpoint repositories. Use deep jobs nightly or with
+ASK_MAX_ANALYSIS_SECONDS/ASK_PROGRESS when CI needs an explicit budget.
 
 [bold]Start here — Java/Spring analysis:[/bold]
   posture . --diff dev:prod    [dim]# effective access, two profile sets (exp.)[/dim]
@@ -881,9 +883,24 @@ def _enforce_format(command: str, fmt: str) -> None:
 
 
 def _safe_write_file(path: "Path", content: str) -> None:
-    """Write content to path, emitting a clean JSON error on I/O failure."""
+    """Atomically write content to path, emitting a clean JSON error on I/O failure."""
     try:
-        path.write_text(content, encoding="utf-8")
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_name(f".{path.name}.tmp-{os.getpid()}-{time.time_ns()}")
+        tmp.write_text(content, encoding="utf-8")
+        tmp.replace(path)
+        try:
+            from sourcecode.runs import active_run
+            run = active_run()
+            if run is not None:
+                run.write(
+                    status="running",
+                    output_path=path,
+                    output_size=path.stat().st_size,
+                )
+        except Exception:
+            pass
     except OSError as _exc:
         _emit_error_json(
             INVALID_INPUT_CODE,
@@ -968,6 +985,50 @@ def _active_command_context() -> "tuple[str, Optional[Path]]":
 
 
 _EXPENSIVE_ANALYSIS_TTL_SECONDS = 6 * 60 * 60
+_ANALYSIS_CLASSES: dict[str, tuple[str, int, str]] = {
+    "spring-audit": ("repo-wide", 600, "use nightly/deep tier on large repositories"),
+    "risk": ("deep", 1200, "run `ask spring-audit` or a saved `risk.json` first"),
+    "audit-report": ("deep", 1200, "reuse `--from-risk risk.json` or schedule nightly"),
+    "verify --init": ("repo-wide", 600, "derive contracts outside pre-commit"),
+    "verify": ("core", 60, "run with a larger CI budget or narrow the contract set"),
+    "migrate-check": ("repo-wide", 600, "run inventory in CI and deep migration checks nightly"),
+}
+
+
+def _analysis_budget(command: str) -> dict[str, Any]:
+    cls, recommended, fallback = _ANALYSIS_CLASSES.get(
+        command, ("repo-wide", 600, "run this command in a supervised or nightly job")
+    )
+    configured: Optional[float] = None
+    raw = os.environ.get("ASK_MAX_ANALYSIS_SECONDS")
+    if raw:
+        try:
+            configured = float(raw)
+        except ValueError:
+            configured = None
+    return {
+        "class": cls,
+        "recommended_min_seconds": recommended,
+        "configured_max_seconds": configured,
+        "fallback": fallback,
+    }
+
+
+def _enforce_analysis_budget(command: str, budget: dict[str, Any]) -> None:
+    configured = budget.get("configured_max_seconds")
+    recommended = float(budget.get("recommended_min_seconds") or 0)
+    if configured is None or float(configured) >= recommended:
+        return
+    _emit_error_json(
+        INVALID_INPUT_CODE,
+        (
+            f"{command} is a {budget.get('class')} analysis and the configured "
+            f"budget ({configured:g}s) is below its safe floor ({recommended:g}s)."
+        ),
+        hint=str(budget.get("fallback") or "raise ASK_MAX_ANALYSIS_SECONDS"),
+        expected=f"ASK_MAX_ANALYSIS_SECONDS >= {recommended:g}",
+    )
+    raise typer.Exit(code=2)
 
 
 def _analysis_lock_path(path: Path) -> Path:
@@ -1051,8 +1112,14 @@ def _emit_analysis_contention_warning(command: str, path: Path, phase: str) -> N
 @contextlib.contextmanager
 def _expensive_analysis_scope(command: str, path: Path, phase: str):
     """Register a long repository-wide analysis and warn on concurrent runs."""
+    from sourcecode.runs import RunRecord, reset_active_run, set_active_run
+
     lock_path = _analysis_lock_path(path)
     _emit_analysis_contention_warning(command, path, phase)
+    budget = _analysis_budget(command)
+    _enforce_analysis_budget(command, budget)
+    run_record = RunRecord.start(path, command, phase, budget=budget)
+    run_token = set_active_run(run_record)
     token = f"{os.getpid()}:{time.time_ns()}"
     owns_lock = False
     if _active_analysis_record(lock_path) is None:
@@ -1077,6 +1144,12 @@ def _expensive_analysis_scope(command: str, path: Path, phase: str):
             owns_lock = False
     try:
         yield
+        if run_record is not None:
+            run_record.write(status="complete", exit_code=0)
+    except BaseException as exc:
+        if run_record is not None:
+            run_record.write(status="failed", exit_code=1, error=str(exc))
+        raise
     finally:
         if owns_lock:
             try:
@@ -1088,6 +1161,7 @@ def _expensive_analysis_scope(command: str, path: Path, phase: str):
                     lock_path.unlink()
                 except OSError:
                     pass
+        reset_active_run(run_token)
 
 
 def _emit_command_output(
@@ -8026,6 +8100,11 @@ def audit_report_cmd(
     format: str = typer.Option(
         "json", "--format", "-f", help="Output format: json, yaml or markdown."
     ),
+    from_risk: Optional[Path] = typer.Option(
+        None,
+        "--from-risk",
+        help="Reuse an existing `ask risk -o risk.json` payload instead of recomputing risk.",
+    ),
     copy: bool = _copy_option(),
 ) -> None:
     """[EXPERIMENTAL] Human audit bundle over existing ASK evidence, optionally signed.
@@ -8044,6 +8123,7 @@ def audit_report_cmd(
     \b
     Examples:
       ask audit-report .
+      ask risk . -o risk.json && ask audit-report . --from-risk risk.json
       ask audit-report . --profile prod --format markdown
       ask audit-report . --sign-key audit.key -o audit-report.json
     """
@@ -8079,12 +8159,42 @@ def audit_report_cmd(
                 expected="a non-empty key file",
             )
             raise typer.Exit(code=1)
+    risk_payload = None
+    if from_risk is not None:
+        risk_path = Path(from_risk).expanduser()
+        if not risk_path.is_file():
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"--from-risk must name a readable risk JSON file (got {str(from_risk)!r}).",
+                hint="Example: ask risk . -o risk.json && ask audit-report . --from-risk risk.json",
+                expected="an existing JSON file produced by `ask risk`",
+            )
+            raise typer.Exit(code=1)
+        try:
+            risk_payload = json.loads(risk_path.read_text(encoding="utf-8"))
+        except Exception as exc:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"--from-risk is not valid JSON: {exc}",
+                hint="Regenerate it with: ask risk . -o risk.json",
+                expected="a JSON object produced by `ask risk`",
+            )
+            raise typer.Exit(code=1)
+        if not isinstance(risk_payload, dict) or "risks" not in risk_payload:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                "--from-risk does not look like an `ask risk` payload.",
+                hint="Regenerate it with: ask risk . -o risk.json",
+                expected="a JSON object with a `risks` array",
+            )
+            raise typer.Exit(code=1)
 
     _prog = Progress()
     _prog.start("packaging audit evidence")
     try:
         data = build_audit_report(
             path, profiles=_profile_set(profile), sign_key=key_bytes,
+            risk_payload=risk_payload,
         )
     finally:
         _prog.stop()

{sourcecode-4.9.1 → sourcecode-4.10.0}/src/sourcecode/progress.py

@@ -1,6 +1,7 @@
-"""Lightweight terminal progress indicator for long-running commands.
+"""Lightweight progress indicator for long-running commands.
 
-Writes only to stderr. Zero-cost when stderr is not a TTY or CI is detected.
+Writes only to stderr. Zero-cost when stderr is not a TTY or CI is detected,
+unless ASK_PROGRESS=1 explicitly requests line heartbeats for supervised jobs.
 Thread-safe; stop() is idempotent.
 """
 from __future__ import annotations
@@ -15,6 +16,8 @@ _FRAMES = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")
 
 
 def _terminal_capable() -> bool:
+    if os.environ.get("ASK_PROGRESS", "").lower() in ("1", "true", "yes", "on"):
+        return True
     if not sys.stderr.isatty():
         return False
     if os.environ.get("TERM") in ("dumb", ""):
@@ -43,6 +46,11 @@ class Progress:
 
     def __init__(self) -> None:
         self._enabled = _terminal_capable()
+        self._line_mode = self._enabled and not sys.stderr.isatty()
+        try:
+            self._interval = max(0.5, float(os.environ.get("ASK_PROGRESS_INTERVAL", "5")))
+        except ValueError:
+            self._interval = 5.0
         self._phase = ""
         self._t0 = time.monotonic()
         self._lock = threading.Lock()
@@ -81,7 +89,8 @@ class Progress:
         self._stop_event.set()
         if self._thread:
             self._thread.join(timeout=1.0)
-        sys.stderr.write("\r\033[K")
+        if not self._line_mode:
+            sys.stderr.write("\r\033[K")
         sys.stderr.flush()
         return elapsed
 
@@ -91,17 +100,23 @@ class Progress:
         if not self._enabled:
             return
         t = f"{elapsed:.1f}s" if elapsed < 60 else f"{elapsed / 60:.1f}m"
-        sys.stderr.write(f"✓ done ({t})\n")
+        prefix = "[ask] " if self._line_mode else "✓ "
+        sys.stderr.write(f"{prefix}done ({t})\n")
         sys.stderr.flush()
 
     def _loop(self) -> None:
         idx = 0
-        while not self._stop_event.wait(timeout=0.08):
+        interval = self._interval if self._line_mode else 0.08
+        while not self._stop_event.wait(timeout=interval):
             frame = _FRAMES[idx % len(_FRAMES)]
             elapsed = time.monotonic() - self._t0
             with self._lock:
                 phase = self._phase
-            line = f"\r{frame} {phase} ({elapsed:.1f}s)"
+            if self._line_mode:
+                t = f"{elapsed:.1f}s" if elapsed < 60 else f"{elapsed / 60:.1f}m"
+                line = f"[ask] progress phase={phase} elapsed={t}\n"
+            else:
+                line = f"\r{frame} {phase} ({elapsed:.1f}s)"
             try:
                 sys.stderr.write(line)
                 sys.stderr.flush()

{sourcecode-4.9.1 → sourcecode-4.10.0}/src/sourcecode/release_info.py

@@ -27,7 +27,7 @@ from typing import Any, Optional
 #: The date `__version__` was released, from that version's CHANGELOG entry.
 #: `tests/test_release_info.py` fails the build if the two disagree, so this is
 #: a copy of a fact rather than a second authority for it.
-RELEASE_DATE = "2026-08-04"
+RELEASE_DATE = "2026-08-05"
 
 #: Releases per day, measured over the 30 releases before this one (the same
 #: computation the test re-runs against the CHANGELOG). Stable across window

sourcecode-4.10.0/src/sourcecode/runs.py

@@ -0,0 +1,136 @@
+"""Durable run records for long ASK analyses."""
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from contextvars import ContextVar
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+_ACTIVE_RUN: ContextVar[Optional["RunRecord"]] = ContextVar("ask_active_run", default=None)
+
+
+def _now() -> float:
+    return time.time()
+
+
+def _runs_dir(root: Path) -> Path:
+    return Path(root).resolve() / ".ask" / "runs"
+
+
+@dataclass
+class RunRecord:
+    root: Path
+    command: str
+    phase: str
+    run_id: str
+    path: Path
+    budget: Optional[dict[str, Any]] = None
+
+    @classmethod
+    def start(
+        cls,
+        root: Path,
+        command: str,
+        phase: str,
+        budget: Optional[dict[str, Any]] = None,
+    ) -> Optional["RunRecord"]:
+        try:
+            directory = _runs_dir(root)
+            directory.mkdir(parents=True, exist_ok=True)
+            run_id = f"{int(_now())}-{os.getpid()}-{uuid.uuid4().hex[:8]}"
+            path = directory / f"{run_id}.json"
+            record = cls(
+                root=Path(root).resolve(), command=command, phase=phase,
+                run_id=run_id, path=path, budget=budget,
+            )
+            record.write(status="running")
+            return record
+        except OSError:
+            return None
+
+    def write(
+        self,
+        *,
+        status: str,
+        exit_code: Optional[int] = None,
+        output_path: Optional[Path] = None,
+        output_size: Optional[int] = None,
+        error: Optional[str] = None,
+    ) -> None:
+        payload: dict[str, Any] = {
+            "schema_version": "ask-run-v1",
+            "run_id": self.run_id,
+            "pid": os.getpid(),
+            "command": self.command,
+            "phase": self.phase,
+            "repo": str(self.root),
+            "status": status,
+            "heartbeat_at": _now(),
+        }
+        if self.budget:
+            payload["budget"] = self.budget
+        if status == "running":
+            payload["started_at"] = payload["heartbeat_at"]
+        else:
+            try:
+                previous = json.loads(self.path.read_text(encoding="utf-8"))
+            except Exception:
+                previous = {}
+            payload["started_at"] = previous.get("started_at", payload["heartbeat_at"])
+            payload["finished_at"] = payload["heartbeat_at"]
+            if output_path is None and previous.get("output_path"):
+                output_path = Path(str(previous["output_path"]))
+            if output_size is None and previous.get("output_size_bytes") is not None:
+                try:
+                    output_size = int(previous["output_size_bytes"])
+                except Exception:
+                    output_size = None
+        if exit_code is not None:
+            payload["exit_code"] = exit_code
+        if output_path is not None:
+            payload["output_path"] = str(output_path)
+        if output_size is not None:
+            payload["output_size_bytes"] = output_size
+        if error:
+            payload["error"] = error
+        tmp = self.path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+        tmp.replace(self.path)
+
+
+def classify_run(path: Path) -> dict[str, Any]:
+    """Read one run record and classify recovery state."""
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    status = str(data.get("status") or "unknown")
+    out = data.get("output_path")
+    if status == "running":
+        pid = int(data.get("pid") or 0)
+        alive = False
+        if pid > 0:
+            try:
+                os.kill(pid, 0)
+                alive = True
+            except Exception:
+                alive = False
+        data["recovery_state"] = "running" if alive else "stale"
+    elif out and Path(str(out)).exists() and Path(str(out)).stat().st_size == 0:
+        data["recovery_state"] = "zero_byte_output"
+    else:
+        data["recovery_state"] = status
+    return data
+
+
+def set_active_run(record: Optional[RunRecord]):
+    return _ACTIVE_RUN.set(record)
+
+
+def reset_active_run(token: Any) -> None:
+    _ACTIVE_RUN.reset(token)
+
+
+def active_run() -> Optional[RunRecord]:
+    return _ACTIVE_RUN.get()