pi-harness-runtime 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to `pi-harness-runtime` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-06-29
+
+### Changed
+
+- **Project rename**: `pi-usage-status` → `pi-harness-runtime`
+  - npm package name: `pi-usage-status` → `pi-harness-runtime`
+  - Repository: `ManotLuijiu/pi-usage-status` → `ManotLuijiu/pi-harness-runtime`
+  - Bundled skill: `usage-status` → `harness-runtime` (file path `skills/usage-status/` → `skills/harness-runtime/`)
+  - Status bar key: `usage-status` → `harness-runtime`
+  - **Data directory unchanged**: still `~/.pi/usage-status/` (preserves existing user data)
+  - **Env var unchanged**: still `PI_USAGE_DIR` (preserves existing user configs)
+  - **Extension symlink unchanged**: still `~/.pi/agent/extensions/pi-usage-status` (repointed to renamed project directory)
+  - Added `"files"` whitelist to `package.json` — publish only the 7 runtime `.ts` files, `skills/`, `package.json`, `README.md`, `CHANGELOG.md`, `LICENSE` (excludes `test/`, `ADR/`, `docs/`, `examples/`, `packages/`, `PRD/`, `RFC/`)
+
+## [0.1.0] - 2026-06-26
+
+### Added
+
+- Initial release
+- `/usage` slash command — show Codex-style usage status (model, directory, local tracking, provider mirror)
+- `/usage sync` slash command — open form to manually mirror provider-side quota from console.minimax.io
+- `/usage today` / `/usage week` / `/usage reset` focused views
+- Local SQLite tracking of every assistant message (input/output tokens + cost)
+- Manual provider-mirror JSON at `~/.pi/usage-status/mirror.json` (synced_at, 5h_used_pct, 5h_resets_at, weekly_used_pct, weekly_resets_at)
+- Rolling 5h window aggregation (auto-computed from local data)
+- Rolling weekly window aggregation
+- Reset-time computation (`oldest_request_in_window + window_duration`)
+- Progress bar renderer matching Codex's `[████████░░░░░░░░░░░░]` style
+- Local-vs-mirror divergence detection (warns if local tracking diverges from manual mirror by >5%)
+- Burn-rate projection ("Weekly burn rate: 11.4% / day")
+- Bundled skill `usage-status` (loaded automatically)
+- MIT license

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MooCoding
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# Pi Harness Runtime
+
+**Codex-style `/usage` status for pi coding agent: local token tracking + manual provider mirror.**
+
+[![npm version](https://img.shields.io/npm/v/pi-harness-runtime?style=for-the-badge)](https://www.npmjs.com/package/pi-harness-runtime)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+[![Platform](https://img.shields.io/badge/Platform-macOS%20|20|Linux-blue?style=for-the-badge)]()
+
+## Why Pi Harness Runtime
+
+**3-Source Honest Tracking** — Codex-style `/status` for pi: local-tracked tokens + manually-mirrored provider quota + derived projections. No fake precision, no scraping, no password storage.
+
+**Zero Config** — Works immediately. Auto-tracks every assistant message. Run `/usage sync` once a day to mirror provider quota from `https://platform.minimax.io/console/usage`.
+
+**Local-First Privacy** — All data stays in `~/.pi/usage-status/`. No telemetry, no remote calls, no credential storage. The provider mirror is a 5-second manual entry.
+
+**Derived Insights** — Auto-computes reset times from your data (no provider API needed), burn rate projections, local-vs-mirror divergence warnings.
+
+## Install
+
+```bash
+pi install npm:pi-harness-runtime
+```
+
+Or install locally for development:
+
+```bash
+git clone https://github.com/ManotLuijiu/pi-harness-runtime.git
+ln -s pi-harness-runtime ~/.pi/agent/extensions/pi-harness-runtime
+pi reload
+```
+
+**Important**: Symlink the **directory** into `~/.pi/agent/extensions/`. Pi's loader scans that directory and reads `package.json`'s `pi.extensions` field for multi-file extensions. Don't symlink a single file (relative imports break) or symlink into `node_modules/` (pi doesn't auto-scan there).
+
+No API keys required. No build step (Bun runs `.ts` directly).
+
+Requires Pi v0.37.3+.
+
+## Quick Start
+
+```bash
+/usage           # show full status (model, local tracking, provider mirror)
+/usage sync      # open form to mirror provider-side quota
+/usage today     # focused: today's usage + 5h window
+/usage week      # focused: this week's usage + lifetime totals
+/usage reset     # clear provider mirror (force re-sync)
+```
+
+## Commands
+
+### `/usage`
+
+Show Codex-style usage status. Renders three sections:
+
+```
+Codex-style usage status for pi
+────────────────────────────────────────────────────────────────
+ Model:        minimax/MiniMax-M3
+ Directory:    ~/frappe-bench/apps/thai_business_suite
+
+ ① LOCAL TRACKED (ground truth — we count this)
+    This session:   $0.17 · 142k tokens · 17 requests
+    This 5h:        384k tokens · 23 requests · $0.04
+    This week:      1.2M tokens · 67 requests · $0.13
+    Lifetime:       4592 requests · $81.61
+
+ ② PROVIDER MIRROR (you enter from console.minimax.io)
+    Last sync:      2 min ago [fresh]
+    Provider:       minimax
+    5h limit:       [████████░░░░░░░░░░░░] 18% left (resets in 4h 54m)
+    Weekly limit:   [████████████████░░░░] 81% left (resets in 2d 13h)
+
+ ③ LOCAL RESET TIMES (derived from your data)
+    Local 5h reset:    in 3h 12m (oldest request falls out of window)
+    Local week reset:  in 5d 7h (oldest request falls out of window)
+    Local-vs-mirror:  -12.4% ⚠️  divergence > 5%
+    Burn rate:        11.4% / day → 100% in 2.5 d
+────────────────────────────────────────────────────────────────
+```
+
+### `/usage sync`
+
+Open a 6-prompt form to mirror provider-side quota:
+
+```
+5h used % (0-100) for minimax: [18]
+5h resets in (hours): [4]
+5h resets in (minutes, 0-59): [56]
+Weekly used % (0-100): [72]
+Weekly resets in (days, 0-7): [2]
+Weekly resets in (hours, 0-23): [13]
+```
+
+Saves to `~/.pi/usage-status/mirror.json` and updates the next `/usage` output.
+
+### `/usage today`
+
+Focused view: today's usage + 5h window. Quick check before starting a long session.
+
+### `/usage week`
+
+Focused view: this week's usage + lifetime totals. Good for end-of-week review.
+
+### `/usage reset`
+
+Clear the provider mirror. Local usage log is preserved. Asks for confirmation.
+
+## How It Works
+
+### Data Sources (3-source model)
+
+1. **Local tracked** — every assistant message is logged to `~/.pi/usage-status/usage.jsonl`
+   - Auto-tracked via `message_end` event
+   - Contains: timestamp, model, input/output/cache tokens, cost
+   - Real-time, exact, but only counts THIS pi session
+
+2. **Provider mirror** — manually entered from `https://platform.minimax.io/console/usage`
+   - Stored at `~/.pi/usage-status/mirror.json`
+   - Synced via `/usage sync` form
+   - Ground truth for TOTAL quota (across all clients)
+
+3. **Derived** — burn rate, reset times, divergence
+   - Local reset time = oldest request in window + window duration
+   - Burn rate = mirror weekly % / elapsed days
+   - Divergence warning if local tracking differs from mirror by >5%
+
+### Files Written
+
+| Path | Contents |
+|---|---|
+| `~/.pi/usage-status/usage.jsonl` | Append-only usage log |
+| `~/.pi/usage-status/mirror.json` | Manual provider mirror |
+| (none — pure functions) | CLI helpers in `cli.ts` |
+
+Override location with `PI_USAGE_DIR` env var (useful for testing).
+
+### What's NOT Stored
+
+- Your password (we don't ask for it, ever)
+- Provider session tokens (we don't read browser cookies)
+- Telemetry or remote calls (all local)
+- Auto-send quota (you always confirm any sync)
+
+## Why Manual Mirror?
+
+Most AI providers (MiniMax, Anthropic, OpenAI) don't expose rate limit headers publicly. Two alternatives exist:
+
+| Approach | Pros | Cons |
+|---|---|---|
+| **Manual mirror** (this) | Zero security risk, 5 sec/day | 1 manual entry |
+| **Browser cookie extraction** (pi-web-access does for Gemini Web) | Fully automatic | ~400 LOC platform-specific code, fragile to auth changes |
+| **HTML scraping** (assumes cookies work) | Once cookies extracted, parsing is easy | Breaks if page redesigns |
+
+We chose the manual approach because:
+
+1. MiniMax's UI shows reset times like "Resets in 4 hr 56 min" — manual entry is genuinely 5 seconds
+2. Cookie extraction has ongoing maintenance burden
+3. Password storage is a security anti-pattern
+
+If you find yourself needing to sync more than 3x/day, we may add browser cookie extraction as a future enhancement.
+
+## Safety Properties
+
+- ✅ **No auto-tracking of other clients** — local data is just this pi session
+- ✅ **No scraping** — provider mirror is manual
+- ✅ **No fabrication** — divergence warning if local and mirror disagree
+- ✅ **Idempotent** — running `/usage` repeatedly has no side effects
+- ✅ **Privacy-respecting** — all data stays on local disk
+- ✅ **No credentials stored** — passwords, tokens, cookies: none
+
+## Architecture
+
+```
+pi-harness-runtime/
+├── index.ts              # entry — exports default (pi: ExtensionAPI)
+├── tracker.ts            # UsageTracker — JSONL writer/reader
+├── mirror.ts             # MirrorStore — JSON read/write + freshness check
+├── windows.ts            # WindowAggregator — pure aggregation functions
+├── renderer.ts           # StatusRenderer — Codex-style progress bars
+├── sync-form.ts          # /usage sync form handling
+├── cli.ts                # shared pure helpers (paths, formatting, IO)
+├── skills/
+│   └── harness-runtime/
+│       └── SKILL.md      # bundled skill (auto-loaded)
+├── test/                 # node --test
+│   ├── cli.test.mjs
+│   ├── tracker.test.mjs
+│   ├── mirror.test.mjs
+│   ├── windows.test.mjs
+│   ├── renderer.test.mjs
+│   └── sync-form.test.mjs
+├── package.json          # "pi" field declares extensions + skills
+├── README.md
+├── CHANGELOG.md
+├── LICENSE               # MIT
+└── .gitignore
+```
+
+## Related
+
+- [pi-web-access](https://github.com/nicobailon/pi-web-access) — web search + URL fetching for pi (inspiration for this package's structure)
+- [context-mode](https://github.com/MiniMax-AI/context-mode) — context-window tracking (complementary)
+- [pi-coding-agent](https://github.com/earendil-works/pi-coding-agent) — the underlying pi agent
+
+## License
+
+MIT © 2026 MooCoding

package/cli.ts

@@ -0,0 +1,111 @@
+/**
+ * Pure helper functions — testable without pi context.
+ * Imported by tracker.ts, mirror.ts, windows.ts, renderer.ts.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+/** Resolve the ~/.pi/usage-status/ directory. Override with PI_USAGE_DIR env var (testing). */
+export function getUsageDir(): string {
+	const override = process.env.PI_USAGE_DIR;
+	if (override) return override;
+	return join(homedir(), ".pi", "usage-status");
+}
+
+/** Resolve the JSONL usage log path. */
+export function getUsageLogPath(): string {
+	return join(getUsageDir(), "usage.jsonl");
+}
+
+/** Resolve the mirror JSON path. */
+export function getMirrorPath(): string {
+	return join(getUsageDir(), "mirror.json");
+}
+
+/** Ensure the directory exists. Idempotent. */
+export function ensureUsageDir(): void {
+	const dir = getUsageDir();
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+}
+
+/** Read the JSONL usage log as an array of UsageRecord. Returns [] if missing. */
+export function readJsonl<T>(path: string): T[] {
+	if (!existsSync(path)) return [];
+	const text = readFileSync(path, "utf-8");
+	const out: T[] = [];
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			out.push(JSON.parse(trimmed) as T);
+		} catch {
+			// skip corrupted line
+		}
+	}
+	return out;
+}
+
+/** Append a single JSON line to a JSONL file. */
+export function appendJsonl(path: string, record: unknown): void {
+	ensureUsageDir();
+	const line = JSON.stringify(record) + "\n";
+	appendFileSync(path, line, "utf-8");
+}
+
+/** Read JSON file safely. Returns null if missing or corrupted. */
+export function readJson(path: string): unknown | null {
+	if (!existsSync(path)) return null;
+	try {
+		return JSON.parse(readFileSync(path, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+
+/** Write JSON file (creates parent dir if needed). */
+export function writeJson(path: string, data: unknown): void {
+	ensureUsageDir();
+	if (!existsSync(dirname(path))) {
+		mkdirSync(dirname(path), { recursive: true });
+	}
+	writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+/** Format milliseconds as "Xh Ym" or "Xd Yh" or "Xm" or "Xs". */
+export function formatDuration(ms: number): string {
+	const abs = Math.max(0, Math.floor(ms / 1000));
+	const sec = abs % 60;
+	const min = Math.floor(abs / 60) % 60;
+	const hr = Math.floor(abs / 3600) % 24;
+	const day = Math.floor(abs / 86400);
+	if (day > 0) return `${day}d ${hr}h`;
+	if (hr > 0) return `${hr}h ${min}m`;
+	if (min > 0) return `${min}m`;
+	return `${sec}s`;
+}
+
+/** Format a timestamp as relative time "X min ago". */
+export function formatRelative(fromIso: string, nowMs: number): string {
+	const fromMs = Date.parse(fromIso);
+	if (isNaN(fromMs)) return "unknown";
+	const deltaMs = nowMs - fromMs;
+	return formatDuration(deltaMs) + " ago";
+}
+
+/** Format a token count with k/M suffix. */
+export function formatTokens(n: number): string {
+	if (n < 1000) return String(n);
+	if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
+	return `${(n / 1_000_000).toFixed(2)}M`;
+}
+
+/** Format USD cost with 2-4 decimals depending on size. */
+export function formatUsd(n: number): string {
+	if (n < 0.01) return `$${n.toFixed(4)}`;
+	if (n < 100) return `$${n.toFixed(2)}`;
+	return `$${n.toFixed(0)}`;
+}

package/index.ts

@@ -0,0 +1,291 @@
+/**
+ * pi-harness-runtime — Codex-style /usage status for pi.
+ *
+ * Slash commands:
+ *   /usage         — show full status (model, local tracking, provider mirror)
+ *   /usage sync    — open form to manually mirror provider-side quota
+ *   /usage today   — focused: this 5h + today (UTC)
+ *   /usage week    — focused: this week + lifetime
+ *   /usage reset   — clear mirror (forces re-sync)
+ *
+ * Auto-tracks every assistant message via the message_end event.
+ * Stores data in ~/.pi/usage-status/  (override with PI_USAGE_DIR for testing).
+ *
+ * No build step — Bun runs this .ts file directly.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { UsageTracker } from "./tracker.ts";
+import { MirrorStore, type MirrorRecord } from "./mirror.ts";
+import { aggregateWindows } from "./windows.ts";
+import { renderStatus } from "./renderer.ts";
+import { buildMirrorRecord, parseSyncValues } from "./sync-form.ts";
+
+const PROVIDER_DEFAULT = "minimax"; // can be changed via /usage sync form
+
+export default function (pi: ExtensionAPI) {
+	const tracker = new UsageTracker();
+	const mirrorStore = new MirrorStore();
+
+	// ─── Auto-track every assistant message ──────────────────────────────
+	pi.on("message_end", async (event, ctx) => {
+		if (event.message.role !== "assistant") return;
+		const m = event.message as {
+			usage?: {
+				input?: number;
+				output?: number;
+				cacheRead?: number;
+				cacheWrite?: number;
+				cost?: { total?: number };
+			};
+		};
+		if (!m.usage) return;
+		tracker.append({
+			ts: Date.now(),
+			model: ctx.model?.id ?? "unknown",
+			input: m.usage.input ?? 0,
+			output: m.usage.output ?? 0,
+			cache_read: m.usage.cacheRead ?? 0,
+			cache_write: m.usage.cacheWrite ?? 0,
+			cost: m.usage.cost?.total ?? 0,
+		});
+	});
+
+	// ─── /usage — show full status ───────────────────────────────────────
+	pi.registerCommand("usage", {
+		description: "Show Codex-style usage status (local + provider mirror)",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const local = aggregateWindows(tracker.all());
+			const mirror = mirrorStore.read();
+			const output = renderStatus({
+				model: ctx.model?.id ?? null,
+				cwd: ctx.cwd ?? process.cwd(),
+				local,
+				mirror,
+				mirrorStore,
+				nowMs: Date.now(),
+			});
+			ctx.ui.notify(output, "info");
+		},
+	});
+
+	// ─── /usage sync — open form ─────────────────────────────────────────
+	pi.registerCommand("usage-sync", {
+		description:
+			"Sync provider quota: /usage sync [provider] [h5%,h,h,m,wk%,d,h]",
+		getArgumentCompletions: (prefix: string) => {
+			const opts = ["minimax", "anthropic", "openai", "openrouter"];
+			const filtered = opts.filter((o) => o.startsWith(prefix));
+			return filtered.length > 0
+				? filtered.map((o) => ({ value: o, label: o }))
+				: null;
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const parts = (args || "").trim().split(/\s+/).filter(Boolean);
+			let provider = PROVIDER_DEFAULT;
+			let inlineValues = "";
+			if (parts.length > 0 && !/^\d/.test(parts[0])) {
+				provider = parts[0];
+				inlineValues = parts.slice(1).join(" ");
+			} else if (parts.length > 0) {
+				inlineValues = parts.join(" ");
+			}
+			await openSyncForm(ctx, mirrorStore, provider, inlineValues);
+		},
+	});
+
+	// ─── /usage today — focused view ─────────────────────────────────────
+	pi.registerCommand("usage-today", {
+		description: "Show today's usage + 5h window",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const local = aggregateWindows(tracker.all());
+			const lines = [
+				" Today's usage",
+				"─────────────────────────────────────",
+				` Model:       ${ctx.model?.id ?? "unknown"}`,
+				` Today:       ${local.today.tokens} tokens · ${local.today.requests} requests · $${local.today.cost.toFixed(4)}`,
+				` This 5h:     ${local.five_h.tokens} tokens · ${local.five_h.requests} requests · $${local.five_h.cost.toFixed(4)}`,
+				"",
+				" Run /usage for full status or /usage sync to mirror provider quota.",
+			];
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
+	// ─── /usage week — focused view ──────────────────────────────────────
+	pi.registerCommand("usage-week", {
+		description: "Show this week's usage + lifetime totals",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const local = aggregateWindows(tracker.all());
+			const lines = [
+				" This week's usage",
+				"─────────────────────────────────────",
+				` Model:       ${ctx.model?.id ?? "unknown"}`,
+				` This week:   ${local.weekly.tokens} tokens · ${local.weekly.requests} requests · $${local.weekly.cost.toFixed(4)}`,
+				` Lifetime:    ${local.lifetime.tokens} tokens · ${local.lifetime.requests} requests · $${local.lifetime.cost.toFixed(4)}`,
+				"",
+				" Run /usage for full status with provider mirror.",
+			];
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
+	// ─── /usage reset — clear mirror ─────────────────────────────────────
+	pi.registerCommand("usage-reset", {
+		description: "Clear the provider mirror (force re-sync next time)",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const ok = await ctx.ui.confirm(
+				"Clear provider mirror?",
+				"This will delete ~/.pi/usage-status/mirror.json. Local usage log is preserved.",
+			);
+			if (!ok) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+			// Delete mirror file
+			try {
+				const { unlinkSync, existsSync } = await import("node:fs");
+				if (existsSync(mirrorStore["path"] ?? "")) {
+					// The path is private; use the JSON path getter via internal logic
+					// Cleaner: just unlink the known mirror path
+				}
+				// Simpler: import getMirrorPath and unlink
+				const { getMirrorPath } = await import("./cli.ts");
+				unlinkSync(getMirrorPath());
+				ctx.ui.notify(
+					"Mirror cleared. Run /usage sync to set a new one.",
+					"info",
+				);
+			} catch (e) {
+				ctx.ui.notify(`Failed to clear mirror: ${e}`, "error");
+			}
+		},
+	});
+
+	// ─── Footer status (persistent badge) ────────────────────────────────
+	pi.on("session_start", async (_event, ctx) => {
+		await refreshFooterStatus(ctx, mirrorStore, tracker);
+	});
+
+	pi.on("turn_end", async (_event, ctx) => {
+		await refreshFooterStatus(ctx, mirrorStore, tracker);
+	});
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Helper: refresh persistent footer status with one-line summary
+// ──────────────────────────────────────────────────────────────────────
+async function refreshFooterStatus(
+	ctx: ExtensionCommandContext,
+	mirrorStore: MirrorStore,
+	tracker: UsageTracker,
+) {
+	const local = aggregateWindows(tracker.all());
+	const mirror = mirrorStore.read();
+	const now = Date.now();
+
+	const todayStr = `${(local.today.tokens / 1000).toFixed(1)}k tok · $${local.today.cost.toFixed(3)}`;
+	let summary = `today: ${todayStr}`;
+
+	if (mirror?.h5_used_pct !== undefined) {
+		const left = Math.max(0, 100 - mirror.h5_used_pct);
+		summary += ` · 5h: ${left}% left`;
+	}
+	if (mirror?.weekly_used_pct !== undefined) {
+		const left = Math.max(0, 100 - mirror.weekly_used_pct);
+		summary += ` · week: ${left}% left`;
+	}
+
+	ctx.ui.setStatus("harness-runtime", summary);
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Helper: open sync form using ctx.ui
+//
+// Usage:
+//   /usage sync                          → prompts for values
+//   /usage sync minimax                  → prompts for values
+//   /usage sync minimax 6,4,8,73,2,13    → no prompts, uses inline values
+//
+// Inline format: h5_pct, h5_h, h5_m, weekly_pct, weekly_d, weekly_h
+// ──────────────────────────────────────────────────────────────────────
+async function openSyncForm(
+	ctx: ExtensionCommandContext,
+	mirrorStore: MirrorStore,
+	provider: string,
+	args: string,
+) {
+	let parsed = parseInlineArgs(args);
+
+	if (!parsed) {
+		// Single prompt with comma-separated values
+		const placeholder = "e.g. 6,4,8,73,2,13 (h5%, h5h, h5m, wk%, wkd, wkh)";
+		const answer = await ctx.ui.input(
+			`Sync ${provider} usage — paste as: h5%, h5 reset h, h5 reset m, weekly%, weekly reset d, weekly reset h`,
+			placeholder,
+		);
+		if (!answer) {
+			ctx.ui.notify("Sync cancelled", "info");
+			return;
+		}
+		parsed = parseInlineArgs(answer);
+		if (!parsed) {
+			ctx.ui.notify(
+				`Invalid format. Expected 6 comma-separated numbers.\nGot: "${answer}"`,
+				"error",
+			);
+			return;
+		}
+	}
+
+	const values = {
+		h5_used_pct: parsed[0],
+		h5_resets_h: parsed[1],
+		h5_resets_m: parsed[2],
+		weekly_used_pct: parsed[3],
+		weekly_resets_d: parsed[4],
+		weekly_resets_h: parsed[5],
+	};
+
+	const validationResult = parseSyncValues({
+		h5_used_pct: String(values.h5_used_pct),
+		h5_resets_h: String(values.h5_resets_h),
+		h5_resets_m: String(values.h5_resets_m),
+		weekly_used_pct: String(values.weekly_used_pct),
+		weekly_resets_d: String(values.weekly_resets_d),
+		weekly_resets_h: String(values.weekly_resets_h),
+	});
+	if (!validationResult) {
+		ctx.ui.notify(
+			`Out of range. h5/wk must be 0-100, h/d/m must fit their bounds.`,
+			"error",
+		);
+		return;
+	}
+
+	const record = buildMirrorRecord(validationResult, provider, Date.now());
+	mirrorStore.write(record);
+	ctx.ui.notify(
+		`Mirror synced for ${provider}.\n` +
+			`  5h: ${validationResult.h5_used_pct}% used, resets in ${validationResult.h5_resets_h}h ${validationResult.h5_resets_m}m\n` +
+			`  weekly: ${validationResult.weekly_used_pct}% used, resets in ${validationResult.weekly_resets_d}d ${validationResult.weekly_resets_h}h\n\n` +
+			`Run /usage to see the full status.`,
+		"info",
+	);
+}
+
+/** Parse "6,4,8,73,2,13" → [6,4,8,73,2,13], or null if invalid. */
+function parseInlineArgs(
+	s: string,
+): [number, number, number, number, number, number] | null {
+	const trimmed = s.trim();
+	if (!trimmed) return null;
+	const parts = trimmed.split(/[,\s]+/).filter(Boolean);
+	if (parts.length !== 6) return null;
+	const nums = parts.map((p) => Number(p));
+	if (nums.some((n) => !Number.isFinite(n))) return null;
+	return nums as [number, number, number, number, number, number];
+}