cctally 1.74.0 → 1.75.0

package/bin/_cctally_parser.py

@@ -1055,7 +1055,7 @@ def _build_codex_session_parser(subparsers, name, *, help_text, xref):
     return p
 
 
-def _add_codex_quota_common_args(parser) -> None:
+def _add_codex_quota_common_args(parser, *, sync_by_default: bool = True) -> None:
     """Attach the shared exact-selector/reporting surface for native quotas."""
     parser.add_argument(
         "--root-key", dest="root_key", metavar="FULL_SOURCE_ROOT_KEY",
@@ -1065,10 +1065,16 @@ def _add_codex_quota_common_args(parser) -> None:
         "--limit-key", dest="limit_key", metavar="FULL_LOGICAL_LIMIT_KEY",
         help="Exact case-sensitive logicalLimitKey selector (no prefix matching).",
     )
-    parser.add_argument(
-        "--no-sync", action="store_true",
-        help="Read retained local-rollout quota evidence without a Codex cache sync.",
-    )
+    if sync_by_default:
+        parser.add_argument(
+            "--no-sync", action="store_true",
+            help="Read retained local-rollout quota evidence without a Codex cache sync.",
+        )
+    else:
+        parser.add_argument(
+            "--sync", action="store_true",
+            help="Refresh retained Codex evidence before reading the materialized projection.",
+        )
     parser.add_argument(
         "--config", default=None, metavar="PATH",
         help="Read display settings from PATH for this invocation only.",
@@ -1145,6 +1151,46 @@ def _build_codex_quota_parser(subparsers, name, *, help_text, xref=None):
     return quota
 
 
+def _build_codex_percent_breakdown_parser(subparsers, name, *, help_text, xref=None):
+    """Build the current native seven-day Codex milestone view."""
+    c = _cctally()
+    parser = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Show cumulative and marginal Codex cost at each integer percent
+            threshold for one native 7-day quota cycle, using the same terminal
+            design as `cctally percent-breakdown`.
+            """
+        ),
+        epilog=textwrap.dedent(
+            """\
+            Examples:
+              cctally codex percent-breakdown
+              cctally codex percent-breakdown --root-key <key> --limit-key <key>
+              cctally codex percent-breakdown --reset-at 2026-07-15T15:00:00Z
+            """
+        ),
+    )
+    parser.add_argument(
+        "--reset-at", default=None, metavar="ISO-8601",
+        help="Exact retained 7-day reset timestamp. Defaults to the active cycle.",
+    )
+    parser.add_argument(
+        "--speed", choices=("auto", "standard", "fast"), default="auto",
+        help="Codex pricing tier for query-time cost correlation (default: auto).",
+    )
+    _add_codex_quota_common_args(parser, sync_by_default=False)
+    parser.add_argument(
+        "--tz", default=None, type=_argparse_tz, metavar="TZ",
+        help="Display timezone: local, utc, or IANA name. Overrides config display.tz.",
+    )
+    parser.set_defaults(func=c.cmd_codex_percent_breakdown)
+    return parser
+
+
 def _build_sync_week_parser(subparsers, name, *, help_text, xref=None):
     """Build the `sync-week` parser (registered via _REGISTRATION; #279 S6 W3).
 
@@ -2138,7 +2184,7 @@ def _build_cache_sync_parser(subparsers, name, *, help_text, xref=None):
         "--prune-conversations",
         action="store_true",
         help="Prune conversation transcripts older than "
-             "conversation.retention_days (default 180) now, without a full "
+             "conversation.retention_days (default 90) now, without a full "
              "rebuild. Re-derivable from JSONL; run `cctally db vacuum` to "
              "reclaim the freed disk space.",
     )
@@ -2372,6 +2418,8 @@ def _build_codex_parser(subparsers, name, *, help_text, xref=None):
         help_text="Show Codex token-reuse analytics", fixed_source="codex")
     _build_report_parser(codex_sub, "report",
         help_text="Show Codex quota-window report", fixed_source="codex")
+    _build_codex_percent_breakdown_parser(codex_sub, "percent-breakdown",
+        help_text="Show per-percent cost milestones for one native 7-day cycle")
     _build_codex_quota_parser(codex_sub, "quota",
         help_text="Native root-qualified Codex quota reports")
 
@@ -2800,6 +2848,52 @@ def _build_db_parser(subparsers, name, *, help_text, xref=None):
         help="Required for --db stats (non-re-derivable; may need a re-record)",
     )
     db_recover.set_defaults(func=c.cmd_db_recover)
+    db_repair = db_sub.add_parser(
+        "repair",
+        help="Recover a malformed stats.db through a verified fresh copy",
+    )
+    db_repair.add_argument(
+        "--db",
+        required=True,
+        choices=("stats",),
+        help="Database to repair (stats only; rebuild cache.db instead)",
+    )
+    db_repair.add_argument(
+        "--yes",
+        action="store_true",
+        help="Required: preserve the corrupt original, then replace stats.db",
+    )
+    db_repair.add_argument(
+        "--busy-timeout-ms",
+        dest="busy_timeout_ms",
+        type=int,
+        default=250,
+        help=argparse.SUPPRESS,
+    )
+    db_repair.set_defaults(func=c.cmd_db_repair)
+    db_backup = db_sub.add_parser(
+        "backup",
+        help="Create a consistent SQLite online-backup snapshot",
+    )
+    db_backup.add_argument(
+        "--db",
+        required=True,
+        choices=("cache", "stats"),
+        help="Which DB to back up",
+    )
+    db_backup.add_argument(
+        "--output",
+        dest="backup_output",
+        help="Destination file (default: timestamped sibling; never overwritten)",
+    )
+    db_backup.add_argument(
+        "--busy-timeout-ms",
+        dest="busy_timeout_ms",
+        type=int,
+        default=15000,
+        help=argparse.SUPPRESS,
+    )
+    db_backup.set_defaults(func=c.cmd_db_backup)
     db_checkpoint = db_sub.add_parser(
         "checkpoint",
         help="Drain the WAL (TRUNCATE checkpoint) — fast, non-destructive",

package/bin/_cctally_percent_breakdown.py

@@ -33,6 +33,51 @@ def _cctally():
     return sys.modules["cctally"]
 
 
+def _render_percent_breakdown_terminal(
+    *,
+    week_start_date: str,
+    week_end_date: str,
+    display_start_iso: str | None,
+    display_end_iso: str | None,
+    milestone_list: list[dict[str, object]],
+    tz,
+    empty_message: str = "No percent milestones recorded for this week.",
+) -> str:
+    """Render the canonical weekly per-percent terminal design."""
+    c = _cctally()
+    lines: list[str] = []
+    if display_start_iso and display_end_iso:
+        lines.append(
+            f"Week: {c._format_ts_compact(display_start_iso, tz=tz)} -> "
+            f"{c._format_ts_compact(display_end_iso, tz=tz)}"
+        )
+    else:
+        lines.append(f"Week: {week_start_date}..{week_end_date}")
+    if not milestone_list:
+        lines.append(empty_message)
+        return "\n".join(lines)
+
+    lines.extend(("Percent breakdown:", ""))
+    headers = ["#", "Threshold", "Cumulative Cost", "Marginal Cost", "5h at crossing"]
+    rows: list[list[str]] = []
+    for idx, milestone in enumerate(milestone_list, start=1):
+        percent = int(milestone["percentThreshold"])
+        cumulative = float(milestone["cumulativeCostUSD"])
+        marginal_value = milestone["marginalCostUSD"]
+        five_hour_value = milestone["fiveHourPercentAtCrossing"]
+        rows.append([
+            str(idx),
+            f"{percent}%",
+            f"${cumulative:.6f}",
+            f"${float(marginal_value):.6f}" if marginal_value is not None else "n/a",
+            f"{float(five_hour_value):.0f}%" if five_hour_value is not None else "n/a",
+        ])
+    lines.append(c._boxed_table(
+        headers, rows, ["right", "right", "right", "right", "right"],
+    ))
+    return "\n".join(lines)
+
+
 def cmd_percent_breakdown(args: argparse.Namespace) -> int:
     c = _cctally()
     config = c.load_config()
@@ -159,40 +204,20 @@ def cmd_percent_breakdown(args: argparse.Namespace) -> int:
             print(json.dumps(c.stamp_schema_version(output), indent=2))
             return 0
 
-        # Prefer the reset-adjusted ISO timestamps in the terminal header
-        # when available; fall back to the raw dates for legacy installs.
-        if display_start_iso and display_end_iso:
-            print(
-                f"Week: {c._format_ts_compact(display_start_iso, tz=tz)} -> "
-                f"{c._format_ts_compact(display_end_iso, tz=tz)}"
-            )
-        else:
-            print(f"Week: {week_start_date}..{week_end_date}")
-        if not milestone_list:
-            if active_segment > 0:
-                # v1.7.2: distinguish post-credit empty (just got
-                # credited, no crossings yet) from genuinely-empty week.
-                # The pre-credit ledger still exists in the DB — just
-                # filtered out of the body — so the user shouldn't see
-                # "No milestones" and assume the data is gone.
-                print(
-                    "(post-credit segment, no milestones crossed yet)"
-                )
-            else:
-                print("No percent milestones recorded for this week.")
-            return 0
-
-        print("Percent breakdown:\n")
-        headers = ["#", "Threshold", "Cumulative Cost", "Marginal Cost", "5h at crossing"]
-        rows: list[list[str]] = []
-        for idx, m in enumerate(milestone_list, start=1):
-            pct = f"{m['percentThreshold']}%"
-            cum = f"${m['cumulativeCostUSD']:.6f}"
-            marg = f"${m['marginalCostUSD']:.6f}" if m["marginalCostUSD"] is not None else "n/a"
-            fh = f"{m['fiveHourPercentAtCrossing']:.0f}%" if m["fiveHourPercentAtCrossing"] is not None else "n/a"
-            rows.append([str(idx), pct, cum, marg, fh])
-
-        print(c._boxed_table(headers, rows, ["right", "right", "right", "right", "right"]))
+        empty_message = (
+            "(post-credit segment, no milestones crossed yet)"
+            if active_segment > 0
+            else "No percent milestones recorded for this week."
+        )
+        print(_render_percent_breakdown_terminal(
+            week_start_date=week_start_date,
+            week_end_date=week_end_date,
+            display_start_iso=display_start_iso,
+            display_end_iso=display_end_iso,
+            milestone_list=milestone_list,
+            tz=tz,
+            empty_message=empty_message,
+        ))
 
         return 0
     finally: