pocketshell 0.3.31__tar.gz → 0.3.33__tar.gz

{pocketshell-0.3.31 → pocketshell-0.3.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pocketshell
-Version: 0.3.31
+Version: 0.3.33
 Summary: Unified server-side Python utility for the PocketShell Android client.
 Project-URL: Homepage, https://github.com/alexeygrigorev/pocketshell
 Project-URL: Issues, https://github.com/alexeygrigorev/pocketshell/issues

{pocketshell-0.3.31 → pocketshell-0.3.33}/pyproject.toml

@@ -8,7 +8,7 @@ name = "pocketshell"
 # scripts/check-pypi-version.sh enforces this; .github/workflows/build.yml
 # runs that check before publishing to PyPI. See
 # tools/pocketshell/README.md ("Release flow") for the bump procedure.
-version = "0.3.31"
+version = "0.3.33"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"

pocketshell-0.3.33/scheduler/README.md

@@ -0,0 +1,74 @@
+# Scheduled usage capture
+
+PocketShell's usage screen is stale-while-revalidate (issue #689): the host
+captures provider usage on a schedule and the app renders the last captured
+reading **instantly** before its own live foreground refresh swaps in fresh
+data.
+
+This directory holds the host-side scheduler units that drive the capture.
+Server-side scheduling is fine — the foreground-only rule (D21) applies to the
+Android app, not the host CLI.
+
+## What `--capture` does
+
+```bash
+pocketshell usage --capture
+```
+
+Fetches usage live (via the daemon when one is running, else a one-shot
+subprocess), then writes two artifacts under
+`${XDG_STATE_HOME:-~/.local/state}/pocketshell/usage/`:
+
+- `usage-latest.json` — the cached latest reading
+  (`{"captured_at": "...Z", "records": [ … ]}`), mode `0600`.
+- `usage-history.jsonl` — an append-only history log, one capture per line,
+  trimmed to the most recent 2000 lines (~83 days at hourly capture; the file
+  stays well under ~1 MB). No external logrotate dependency.
+
+A failed live fetch is **not** cached, so a transient provider hiccup never
+pins a bad reading.
+
+The app reads the cache with:
+
+```bash
+pocketshell usage --cached
+```
+
+which prints `usage-latest.json` instantly (exit 3 with a friendly note when no
+capture has run yet, so the app falls back to a pure live fetch).
+
+## Install (systemd user timer — recommended)
+
+```bash
+mkdir -p ~/.config/systemd/user
+cp pocketshell-usage-capture.service ~/.config/systemd/user/
+cp pocketshell-usage-capture.timer   ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now pocketshell-usage-capture.timer
+
+# Keep the timer running after you log out (so the laptop/server captures
+# on schedule without an active session):
+loginctl enable-linger "$USER"
+```
+
+Check it:
+
+```bash
+systemctl --user list-timers pocketshell-usage-capture.timer
+journalctl --user -u pocketshell-usage-capture.service --no-pager
+```
+
+The `.service` uses `%h/.local/bin/pocketshell` (the `uv tool install` /
+`pipx install` location). Adjust `ExecStart` if `pocketshell` lives elsewhere
+on your `PATH`.
+
+## Install (cron alternative)
+
+For hosts without systemd, an hourly cron line works the same way:
+
+```cron
+# m h dom mon dow command
+17 * * * * $HOME/.local/bin/pocketshell usage --capture >/dev/null 2>&1
+```
+
+(The minute offset spreads the call off the top of the hour.)

pocketshell-0.3.33/scheduler/pocketshell-usage-capture.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=PocketShell usage capture (writes the cached latest reading + history log)
+Documentation=https://github.com/alexeygrigorev/pocketshell/blob/main/docs/usage-panel.md
+
+[Service]
+Type=oneshot
+# Capture usage live, write usage-latest.json + append usage-history.jsonl
+# under $XDG_STATE_HOME/pocketshell/usage/. %h expands to the user's home,
+# so this works with `systemctl --user` (the recommended install).
+ExecStart=%h/.local/bin/pocketshell usage --capture
+# Keep capture failures (a transient provider hiccup) non-fatal for the
+# timer: a single missed capture just means the app shows a slightly older
+# cached reading until the next run.
+SuccessExitStatus=0 1

pocketshell-0.3.33/scheduler/pocketshell-usage-capture.timer

@@ -0,0 +1,15 @@
+[Unit]
+Description=Run PocketShell usage capture hourly
+Documentation=https://github.com/alexeygrigorev/pocketshell/blob/main/docs/usage-panel.md
+
+[Timer]
+# Hourly capture. RandomizedDelaySec spreads the provider API calls so a
+# fleet of hosts does not hit the endpoints all at once on the hour.
+OnCalendar=hourly
+RandomizedDelaySec=300
+# Catch up after the machine was asleep/off so a laptop that missed the
+# hourly tick still refreshes the cache on next boot.
+Persistent=true
+
+[Install]
+WantedBy=timers.target

{pocketshell-0.3.31 → pocketshell-0.3.33}/src/pocketshell/cli.py

@@ -28,6 +28,7 @@ from pocketshell.github import github_group
 from pocketshell.hooks import hooks_group
 from pocketshell.jobs import jobs_group
 from pocketshell.logs import logs_group
+from pocketshell.prune_attachments import prune_attachments_command
 from pocketshell.qr_share import qr_share_command
 from pocketshell.repos import repos_group
 from pocketshell.sessions import sessions_group
@@ -58,6 +59,7 @@ cli.add_command(github_group, name="github")
 cli.add_command(env_group, name="env")
 cli.add_command(hooks_group, name="hooks")
 cli.add_command(logs_group, name="logs")
+cli.add_command(prune_attachments_command, name="prune-attachments")
 cli.add_command(qr_share_command, name="qr-share")
 
 

pocketshell-0.3.33/src/pocketshell/prune_attachments.py

@@ -0,0 +1,372 @@
+"""`pocketshell prune-attachments` — server-side attachment retention backstop.
+
+The PocketShell Android composer uploads each prompt attachment to the
+remote host under ``~/.pocketshell/attachments/<host-scope>/`` (see
+``PromptAttachmentStager.REMOTE_DIRECTORY`` on the client). Nothing on the
+host ever removes those files, so the directory grows unbounded on every
+host the user attaches to (issue #547).
+
+The client already prunes the *active* scope dir on a fresh upload
+(``RemoteAttachmentPruner`` — option 1 in #547). This command is the
+**server-side backstop** (option 2): it runs ON the host, over the whole
+``~/.pocketshell/attachments/`` tree, so even hosts the user stopped
+attaching to are eventually trimmed. It is meant to be invoked by the
+normal ``pocketshell`` plumbing (e.g. on connect / during usage probes) or
+from a maintainer's cron.
+
+Safety bounds (deny-by-default — this deletes files):
+
+- **Scoped to one directory.** Only files directly under
+  ``~/.pocketshell/attachments/<scope>/`` (depth-2 from the root) are ever
+  considered. The root and the per-scope directories themselves are never
+  deleted; the user's own files outside the attachments tree are never
+  touched. The resolved root must stay inside ``$HOME`` or the command
+  refuses to run.
+- **Regular files only.** Symlinks, directories, sockets, and anything
+  that is not a plain regular file is skipped — a symlink inside the
+  attachments dir can never be used to delete a file elsewhere.
+- **Age bound (TTL).** A file is a deletion candidate only when its mtime
+  is strictly older than ``DEFAULT_TTL_DAYS`` (14 days).
+- **Size cap.** After the TTL pass, if the *surviving* attachments still
+  exceed ``DEFAULT_MAX_TOTAL_BYTES`` (256 MiB), the oldest survivors are
+  deleted (oldest-first) until the tree is back under the cap. Files
+  younger than ``PROTECT_NEWEST_HOURS`` (24h) are never deleted by the
+  size cap so an active session's just-uploaded files are spared even
+  during a big backlog clear.
+- **Dry-run default off, but ``--dry-run`` reports without deleting.**
+
+The command is best-effort and never raises on a per-file delete error
+(permissions, races) — it logs the failure into the result summary and
+continues, so a single bad file can't wedge the whole prune.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import click
+
+# Retention tuning knobs. Kept as module constants so both the CLI and the
+# unit suite reference one source of truth.
+DEFAULT_TTL_DAYS: int = 14
+DEFAULT_MAX_TOTAL_BYTES: int = 256 * 1024 * 1024  # 256 MiB
+PROTECT_NEWEST_HOURS: int = 24
+
+# The attachments root, relative to ``$HOME``. Mirrors the client's
+# ``PromptAttachmentStager.REMOTE_DIRECTORY``.
+ATTACHMENTS_RELATIVE_ROOT = Path(".pocketshell") / "attachments"
+
+_SECONDS_PER_DAY = 24 * 60 * 60
+_SECONDS_PER_HOUR = 60 * 60
+
+
+@dataclass
+class DeletedFile:
+    """One file the prune removed (or would remove in dry-run)."""
+
+    path: str
+    size: int
+    age_days: float
+    reason: str  # "ttl" or "size-cap"
+
+
+@dataclass
+class PruneResult:
+    """Structured summary of a prune pass (CLI emits this as JSON)."""
+
+    root: str
+    scanned_files: int = 0
+    scanned_bytes: int = 0
+    deleted: list[DeletedFile] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    dry_run: bool = False
+    skipped_root_missing: bool = False
+
+    @property
+    def deleted_count(self) -> int:
+        return len(self.deleted)
+
+    @property
+    def deleted_bytes(self) -> int:
+        return sum(d.size for d in self.deleted)
+
+    def to_dict(self) -> dict:
+        return {
+            "root": self.root,
+            "dry_run": self.dry_run,
+            "skipped_root_missing": self.skipped_root_missing,
+            "scanned_files": self.scanned_files,
+            "scanned_bytes": self.scanned_bytes,
+            "deleted_count": self.deleted_count,
+            "deleted_bytes": self.deleted_bytes,
+            "deleted": [
+                {
+                    "path": d.path,
+                    "size": d.size,
+                    "age_days": round(d.age_days, 3),
+                    "reason": d.reason,
+                }
+                for d in self.deleted
+            ],
+            "errors": self.errors,
+        }
+
+
+@dataclass
+class _Candidate:
+    path: Path
+    size: int
+    mtime: float
+
+
+def resolve_attachments_root(home: Optional[Path] = None) -> Path:
+    """Resolve ``~/.pocketshell/attachments`` from ``$HOME``.
+
+    Pulled out so the unit suite can point it at a tmp dir. Uses the
+    ``home`` argument when given, otherwise ``Path.home()``.
+    """
+    base = home if home is not None else Path.home()
+    return (base / ATTACHMENTS_RELATIVE_ROOT).resolve()
+
+
+def _iter_attachment_files(root: Path) -> list[_Candidate]:
+    """Collect regular files exactly two levels under ``root``.
+
+    Layout is ``root/<scope>/<file>``. We deliberately do NOT recurse
+    deeper and we never follow symlinks: a candidate must be a real
+    regular file (``Path.is_file()`` follows symlinks, so we additionally
+    reject symlinks with ``is_symlink()``).
+    """
+    candidates: list[_Candidate] = []
+    for scope_dir in _safe_iterdir(root):
+        # Only descend into real directories that are direct children of
+        # the root — never symlinked dirs (which could point outside the
+        # attachments tree).
+        if scope_dir.is_symlink() or not scope_dir.is_dir():
+            continue
+        for entry in _safe_iterdir(scope_dir):
+            if entry.is_symlink():
+                continue
+            if not entry.is_file():
+                continue
+            try:
+                stat = entry.stat()
+            except OSError:
+                continue
+            candidates.append(
+                _Candidate(path=entry, size=stat.st_size, mtime=stat.st_mtime)
+            )
+    return candidates
+
+
+def _safe_iterdir(directory: Path) -> list[Path]:
+    try:
+        return sorted(directory.iterdir())
+    except OSError:
+        return []
+
+
+def prune_attachments(
+    root: Path,
+    *,
+    now: float,
+    ttl_days: int = DEFAULT_TTL_DAYS,
+    max_total_bytes: int = DEFAULT_MAX_TOTAL_BYTES,
+    protect_newest_hours: int = PROTECT_NEWEST_HOURS,
+    dry_run: bool = False,
+) -> PruneResult:
+    """Prune attachments under ``root`` by TTL then by size cap.
+
+    ``root`` MUST be the resolved ``~/.pocketshell/attachments`` directory;
+    the caller is responsible for the ``$HOME`` containment check (the CLI
+    does it). ``now`` is the current epoch-seconds (injected so the unit
+    suite is deterministic).
+    """
+    result = PruneResult(root=str(root), dry_run=dry_run)
+
+    if not root.exists() or not root.is_dir():
+        result.skipped_root_missing = True
+        return result
+
+    candidates = _iter_attachment_files(root)
+    result.scanned_files = len(candidates)
+    result.scanned_bytes = sum(c.size for c in candidates)
+
+    ttl_seconds = ttl_days * _SECONDS_PER_DAY
+    protect_seconds = protect_newest_hours * _SECONDS_PER_HOUR
+
+    survivors: list[_Candidate] = []
+
+    # Pass 1 — TTL. A file strictly older than the TTL is deleted.
+    for c in candidates:
+        age = now - c.mtime
+        if age > ttl_seconds:
+            _delete(result, c, now=now, reason="ttl", dry_run=dry_run)
+        else:
+            survivors.append(c)
+
+    # Pass 2 — size cap. If survivors still exceed the cap, delete the
+    # oldest (lowest mtime first) until back under, but never delete a file
+    # younger than the protect window.
+    surviving_bytes = sum(c.size for c in survivors)
+    if surviving_bytes > max_total_bytes:
+        # Oldest first.
+        for c in sorted(survivors, key=lambda x: x.mtime):
+            if surviving_bytes <= max_total_bytes:
+                break
+            age = now - c.mtime
+            if age < protect_seconds:
+                continue
+            _delete(result, c, now=now, reason="size-cap", dry_run=dry_run)
+            surviving_bytes -= c.size
+
+    return result
+
+
+def _delete(
+    result: PruneResult,
+    candidate: _Candidate,
+    *,
+    now: float,
+    reason: str,
+    dry_run: bool,
+) -> None:
+    """Record (and, unless dry-run, perform) one deletion. Best-effort."""
+    age_days = (now - candidate.mtime) / _SECONDS_PER_DAY
+    if not dry_run:
+        try:
+            candidate.path.unlink()
+        except OSError as exc:
+            result.errors.append(f"{candidate.path}: {exc}")
+            return
+    result.deleted.append(
+        DeletedFile(
+            path=str(candidate.path),
+            size=candidate.size,
+            age_days=age_days,
+            reason=reason,
+        )
+    )
+
+
+@click.command(
+    name="prune-attachments",
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help=(
+        "Prune the ~/.pocketshell/attachments/ tree on this host.\n\n"
+        "Server-side retention backstop for prompt attachments uploaded by "
+        "the PocketShell composer (issue #547). Deletes regular files older "
+        "than the TTL, then trims the oldest survivors if the tree still "
+        "exceeds the size cap. Only touches files inside the attachments "
+        "directory; never the user's own files. Best-effort: per-file "
+        "errors are reported, not raised."
+    ),
+)
+@click.option(
+    "--ttl-days",
+    type=click.IntRange(min=0),
+    default=DEFAULT_TTL_DAYS,
+    show_default=True,
+    help="Delete attachments strictly older than this many days.",
+)
+@click.option(
+    "--max-total-mib",
+    type=click.IntRange(min=0),
+    default=DEFAULT_MAX_TOTAL_BYTES // (1024 * 1024),
+    show_default=True,
+    help=(
+        "After the TTL pass, trim oldest survivors until the tree is under "
+        "this size (MiB). Files younger than the protect window are spared."
+    ),
+)
+@click.option(
+    "--protect-newest-hours",
+    type=click.IntRange(min=0),
+    default=PROTECT_NEWEST_HOURS,
+    show_default=True,
+    help="Never let the size cap delete files younger than this.",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Report what would be deleted without deleting anything.",
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    help="Emit the prune summary as JSON.",
+)
+def prune_attachments_command(
+    ttl_days: int,
+    max_total_mib: int,
+    protect_newest_hours: int,
+    dry_run: bool,
+    as_json: bool,
+) -> None:
+    """CLI entrypoint for ``pocketshell prune-attachments``."""
+    import time
+
+    home = Path.home().resolve()
+    root = resolve_attachments_root(home)
+
+    # Containment guard: the resolved root must stay inside $HOME. This is a
+    # belt-and-braces check against a tampered $HOME / ATTACHMENTS root.
+    if not _is_within(root, home):
+        raise click.ClickException(
+            f"refusing to prune {root}: not inside $HOME ({home})"
+        )
+
+    result = prune_attachments(
+        root,
+        now=time.time(),
+        ttl_days=ttl_days,
+        max_total_bytes=max_total_mib * 1024 * 1024,
+        protect_newest_hours=protect_newest_hours,
+        dry_run=dry_run,
+    )
+
+    if as_json:
+        click.echo(json.dumps(result.to_dict(), indent=2))
+        return
+
+    if result.skipped_root_missing:
+        click.echo(f"no attachments directory at {root}; nothing to prune.")
+        return
+
+    verb = "would delete" if dry_run else "deleted"
+    mib = result.deleted_bytes / (1024 * 1024)
+    click.echo(
+        f"scanned {result.scanned_files} files "
+        f"({result.scanned_bytes / (1024 * 1024):.1f} MiB); "
+        f"{verb} {result.deleted_count} ({mib:.1f} MiB)."
+    )
+    for d in result.deleted:
+        click.echo(f"  {verb}: {d.path} ({d.reason}, {d.age_days:.1f}d)")
+    for err in result.errors:
+        click.echo(f"  error: {err}", err=True)
+
+
+def _is_within(path: Path, parent: Path) -> bool:
+    """True when ``path`` is ``parent`` or a descendant of it."""
+    try:
+        path.relative_to(parent)
+        return True
+    except ValueError:
+        return False
+
+
+__all__ = [
+    "DEFAULT_TTL_DAYS",
+    "DEFAULT_MAX_TOTAL_BYTES",
+    "PROTECT_NEWEST_HOURS",
+    "ATTACHMENTS_RELATIVE_ROOT",
+    "DeletedFile",
+    "PruneResult",
+    "resolve_attachments_root",
+    "prune_attachments",
+    "prune_attachments_command",
+]

{pocketshell-0.3.31 → pocketshell-0.3.33}/src/pocketshell/usage.py

@@ -536,6 +536,37 @@ def _try_daemon_usage_fetch(
         "No effect on the one-shot subprocess path, which always runs fresh."
     ),
 )
+@click.option(
+    "--capture",
+    "capture",
+    is_flag=True,
+    help=(
+        "Fetch usage live, write the cached latest reading + append to the "
+        "history log under $XDG_STATE_HOME/pocketshell/usage/, then exit. "
+        "Run this on a schedule (cron / systemd timer). Implies --json."
+    ),
+)
+@click.option(
+    "--cached",
+    "cached",
+    is_flag=True,
+    help=(
+        "Emit the last captured reading instantly (no live fetch) as a JSON "
+        "document {captured_at, records} for the app's stale-while-revalidate "
+        "render. Exits non-zero if no capture exists yet. Implies --json."
+    ),
+)
+@click.option(
+    "--reset-events",
+    "reset_events",
+    is_flag=True,
+    help=(
+        "Emit the recorded limit/session reset events (#690) as a JSON "
+        "document {reset_events: [...]} from the history log. The app reads "
+        "this to surface 'limits reset at <time>' on next open. Emits an "
+        "empty list when no resets have been detected yet. Implies --json."
+    ),
+)
 @click.pass_context
 def usage_command(
     ctx: click.Context,
@@ -543,6 +574,9 @@ def usage_command(
     json_output: bool = False,
     no_daemon: bool = False,
     no_cache: bool = False,
+    capture: bool = False,
+    cached: bool = False,
+    reset_events: bool = False,
 ) -> None:
     """Report quota / usage for coding-agent providers on this host.
 
@@ -552,7 +586,32 @@ def usage_command(
     it falls through to ``quse [provider] [--json]`` as a one-shot
     subprocess. JSON output is normalized into PocketShell's schema so
     the app is not pinned to provider-specific `quse` quirks.
+
+    ``--capture`` and ``--cached`` implement the stale-while-revalidate
+    cache (#689): a scheduled ``--capture`` writes the latest reading +
+    history log on the host, and the app reads ``--cached`` for an instant
+    populated render before its own live foreground refresh swaps in fresh
+    data.
     """
+    # `--cached` emits the last captured reading instantly; `--capture`
+    # fetches live and persists the cache + history. Both bypass the
+    # normal stdout-proxy path below. They imply JSON output.
+    if reset_events:
+        exit_code = _emit_reset_events()
+        if exit_code != 0:
+            ctx.exit(exit_code)
+        return
+    if cached:
+        exit_code = _emit_cached_usage()
+        if exit_code != 0:
+            ctx.exit(exit_code)
+        return
+    if capture:
+        exit_code = _capture_usage(provider, no_daemon=no_daemon)
+        if exit_code != 0:
+            ctx.exit(exit_code)
+        return
+
     # JSON output is the format the daemon caches against (NDJSON
     # straight from `quse --json`). Human-readable output is rare and
     # not on the Android hot path, so it does not get the daemon
@@ -586,6 +645,100 @@ def usage_command(
         ctx.exit(exit_code)
 
 
+def _fetch_usage_ndjson(
+    provider: Optional[str],
+    *,
+    no_daemon: bool,
+) -> tuple[Optional[str], str, int]:
+    """Fetch live usage NDJSON for the cache capture.
+
+    Returns ``(stdout, stderr, returncode)`` where ``stdout`` is the
+    normalized NDJSON (or ``None`` when ``quse`` is missing). Mirrors the
+    command's own daemon-then-subprocess fall-through so a scheduled
+    ``--capture`` benefits from the daemon cache when one is live.
+    """
+    if not no_daemon:
+        envelope = _try_daemon_usage_fetch(provider, no_cache=False)
+        if envelope is not None:
+            stdout = normalize_usage_stdout(str(envelope.get("stdout") or ""))
+            stderr = str(envelope.get("stderr") or "")
+            return stdout, stderr, int(envelope.get("returncode", 0))
+
+    quse_path = _resolve_quse_binary()
+    if quse_path is None:
+        return (
+            None,
+            (
+                "pocketshell: `quse` is not installed on this host. "
+                "Install it via `uv tool install quse` or `pipx install quse` "
+                "and re-run.\n"
+            ),
+            127,
+        )
+    args: list[str] = [quse_path]
+    if provider:
+        args.append(provider)
+    args.append("--json")
+    completed = subprocess.run(args, check=False, capture_output=True, text=True)
+    return normalize_usage_stdout(completed.stdout), completed.stderr, completed.returncode
+
+
+def _capture_usage(provider: Optional[str], *, no_daemon: bool) -> int:
+    """Fetch usage live and persist the cache + history log, then report.
+
+    Designed to run on a schedule. On a successful fetch it writes
+    ``usage-latest.json`` and appends to ``usage-history.jsonl`` under
+    ``$XDG_STATE_HOME/pocketshell/usage/`` and echoes the cache object so a
+    cron/systemd log shows what landed. A failed fetch is NOT cached so a
+    transient provider hiccup never pins a bad reading.
+    """
+    from pocketshell import usage_capture as _capture
+
+    stdout, stderr, returncode = _fetch_usage_ndjson(provider, no_daemon=no_daemon)
+    if returncode != 0 or stdout is None:
+        if stderr:
+            sys.stderr.write(stderr)
+        return returncode if returncode != 0 else 1
+
+    cache_obj = _capture.write_capture(stdout)
+    sys.stdout.write(json.dumps(cache_obj, sort_keys=True) + "\n")
+    return 0
+
+
+def _emit_cached_usage() -> int:
+    """Emit the last captured reading as a JSON document, or exit non-zero.
+
+    Returns exit code 0 when a cache exists (its JSON document is written to
+    stdout), or 3 with a friendly stderr note when no capture has run yet so
+    the app can fall back to a pure live fetch.
+    """
+    from pocketshell import usage_capture as _capture
+
+    document = _capture.cached_document()
+    if document is None:
+        sys.stderr.write(
+            "pocketshell: no captured usage yet. "
+            "Run `pocketshell usage --capture` (or wait for the scheduled "
+            "capture) to populate the cache.\n"
+        )
+        return 3
+    sys.stdout.write(document)
+    return 0
+
+
+def _emit_reset_events() -> int:
+    """Emit recorded reset events (#690) as a JSON document.
+
+    Always exits 0: the document is ``{"reset_events": [...]}`` (empty list
+    when no resets have been detected/logged yet), so the app can read it
+    unconditionally and surface "limits reset at <time>" when present.
+    """
+    from pocketshell import usage_reset as _reset
+
+    sys.stdout.write(_reset.reset_events_document())
+    return 0
+
+
 def _run_quse_json(args: Sequence[str]) -> int:
     """Invoke ``quse`` and normalize JSON stdout before proxying it."""
     quse_path = _resolve_quse_binary()