copilot-usage-studio 0.1.0 → 0.2.1

package/dist/copilot-usage-studio/browser/styles-7RDDQXQV.css

@@ -0,0 +1 @@
+*{box-sizing:border-box}html,body{margin:0;min-height:100%;font-family:Aptos,Segoe UI Variable,Segoe UI,Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,sans-serif;font-size:14px;line-height:1.45;background:#090d14;color:#d7dde7;text-rendering:optimizeLegibility;-webkit-font-smoothing:antialiased}html[data-theme=light],html[data-theme=light] body{background:#f4f7fb;color:#182536}html[data-theme=dark],html[data-theme=dark] body{background:#090d14;color:#d7dde7}button,input,select{font:inherit}code{border:1px solid color-mix(in srgb,var(--accent, #6f5cff) 18%,var(--line, #d7e1ea));border-radius:5px;padding:1px 5px;background:color-mix(in srgb,var(--accent, #6f5cff) 8%,transparent);color:var(--text-strong, #182536);font-family:ui-monospace,SFMono-Regular,Consolas,Liberation Mono,monospace;font-size:.92em}.data-refresh{display:grid;justify-items:end;min-width:0}.data-refresh-button{display:inline-flex;align-items:center;justify-content:center;gap:6px;min-height:32px;border:1px solid var(--line);border-radius:9px;padding:5px 10px;background:var(--control-bg);color:var(--text-strong);font-size:12px;font-weight:760;cursor:pointer;box-shadow:var(--shadow-soft)}.data-refresh-button:hover:not(:disabled){border-color:var(--accent);color:var(--accent)}.data-refresh-button:disabled{cursor:progress;opacity:.72}.refresh-icon{display:grid;place-items:center;width:16px;height:16px;font-size:17px;line-height:1;transform-origin:50% 50%}.refresh-icon.spinning{animation:refresh-spin .8s linear infinite}.data-refresh-status{max-width:190px;overflow:hidden;color:var(--muted-2);font-size:10px;line-height:1.2;text-overflow:ellipsis;white-space:nowrap}.data-refresh.error .data-refresh-status{color:var(--danger-text)}.host-vscode .data-refresh-status{display:none}@keyframes refresh-spin{to{transform:rotate(360deg)}}@media(max-width:760px){.data-refresh-status{display:none}}@media(max-width:520px){.data-refresh-button>span:last-child{display:none}.data-refresh-button{padding-inline:5px}}

package/docs/copilot-memory.md

@@ -0,0 +1,91 @@
+# Copilot Memory
+
+Copilot Usage Studio indexes locally saved GitHub Copilot memories and plans so a developer can see what Copilot has stored across VS Code workspaces.
+
+## Observed storage
+
+Workspace-scoped files:
+
+```text
+<VS Code User>/workspaceStorage/<workspace-id>/GitHub.copilot-chat/memory-tool/memories/
+```
+
+Global files:
+
+```text
+<VS Code User>/globalStorage/github.copilot-chat/memory-tool/memories/
+```
+
+Observed workspace layouts include:
+
+```text
+memories/repo/<topic>.md
+memories/<base64-session-id>/plan.md
+memories/<base64-session-id>/<research>.md
+```
+
+The base64 directory decodes to the same session UUID used by Agent Debug Logs and transcripts. This gives the app a source-backed link between a saved plan or research note and the run that created it.
+
+## Normalized record
+
+Each indexed Markdown file records:
+
+- stable local id derived from its absolute path
+- `kind`: `memory` or `plan`
+- `scope`: `global`, `repository`, `session`, or `workspace`
+- title, excerpt, and full Markdown content
+- workspace name when applicable
+- decoded session id when applicable
+- absolute and relative source paths
+- created and modified timestamps
+- byte, character, and line counts
+
+The scanner reads Markdown files once during the normal local scan. It skips files larger than 1 MiB and caps each memory root at 5,000 files. These limits protect refresh performance without affecting normal observed memory stores, whose files are small.
+
+## Product boundary
+
+Version one is a read-only knowledge library:
+
+- search all saved memory content
+- filter by plan/memory, scope, and workspace
+- read the Markdown source
+- link session-scoped files to imported runs
+- show observed recall frequency, time, session, returned content size, and the following model request
+- open the file or reveal it through the local runtime
+
+The browser does not receive arbitrary filesystem access. Open/reveal actions identify a memory by its scanner-generated id, and the runtime accepts only files present in the current scanned snapshot.
+
+## Observed recall evidence
+
+Agent Debug Logs provide a useful distinction between a memory being available and actually being recalled:
+
+- VS Code injects a memory inventory into model input. The observed inventory names available user, session, and repository memory files, but does not include every file's full contents.
+- When the agent calls the `memory` tool with `command: "view"`, the tool event records the requested memory path and returned content.
+- That tool result is then present in the following model request. The app can therefore say that a specific memory was loaded before a specific model call.
+- The following model call exposes exact total input, cached input, output, and source usage when those fields are present. It does not expose a separate token total or cost for the memory text alone.
+
+In the June 15, 2026 local log sample, 46 JSONL files contained 127 model requests with a memory inventory and 18 explicit memory-tool operations across 11 sessions. Fifteen operations were reads, including repeated reads of the repository memory. These counts establish that recall is observable, but they are only a local sample and not a VS Code API contract.
+
+The recall view shows:
+
+- which memory path was read
+- when and in which session it was read
+- the returned content size
+- the next model call and that call's total token/usage facts
+
+It must not label the entire following request as memory cost or derive an exact memory-only token charge from character count.
+
+## What the app does not claim
+
+A saved memory is evidence that Copilot wrote a local file. A matching `memory view` tool event is evidence that Copilot later recalled it and included the returned content in the request chain.
+
+Therefore the first version does not label memories as useful, stale, harmful, or token-consuming. Those conclusions require a matching Agent Debug Log or request side-file showing that the memory was included in a model request.
+
+Future evidence-backed opportunities:
+
+- flag conflicting or old memories for review
+- compare request input before and after a memory is edited or removed
+- help turn a proven durable memory into repository instructions
+- map repository memories to code/domain areas when paths or content provide a reliable relationship
+
+Editing and deletion remain later work. The files are technically accessible, but VS Code's indexing and lifecycle contract is not documented strongly enough to make destructive management a first-release feature.

package/docs/local-deployment.md

@@ -2,9 +2,9 @@
 
 The app is intended to run locally, near the VS Code data it reads. It should not require a hosted SaaS backend for the core workflow.
 
-Current release posture: early local developer preview. The npm package is prepared and locally verified; clone-and-run remains available until version `0.1.0` is published to the registry.
+Current release posture: early VS Code extension preview. Version `0.2.0` exists on npm as the development/fallback host, but the VS Code extension is the product path.
 
-Packaging foundation now available: the scanner exposes an in-memory Node API through `lib/scanner-api.mjs`. The existing scan command uses that same API and only adds argument parsing plus JSON persistence. This is the common core for the next local host, an `npx` command, Electron packaging, and a future thin VS Code extension.
+Packaging foundation now available: the scanner exposes an in-memory Node API through `lib/scanner-api.mjs`. The existing scan command, local runtime, npm host, and VS Code extension preview use the same scanner/runtime core so behavior stays aligned across hosts.
 
 Supported source today: VS Code GitHub Copilot Chat and Agent local storage. Visual Studio, JetBrains IDEs, Copilot CLI, GitHub.com chat, and GitHub billing exports are outside the current importer scope.
 
@@ -33,7 +33,7 @@ http://127.0.0.1:4200/
 
 Why: this is the fastest loop while the UI and scanner are changing. `npm start` launches the Angular dev server and the local runtime together. The runtime serves the last valid snapshot immediately, performs a background startup scan, and powers the in-app refresh action.
 
-## First Public Release Path
+## Install From npm
 
 The npm package is configured for a one-command local launch:
 
@@ -41,7 +41,7 @@ The npm package is configured for a one-command local launch:
 npx copilot-usage-studio
 ```
 
-This command will become available after the package owner publishes version `0.1.0` to npm. It starts the packaged production UI and scanner runtime on `http://127.0.0.1:4312/` by default.
+This starts the packaged production UI and scanner runtime on `http://127.0.0.1:4312/` by default. It downloads the latest published npm version rather than the current GitHub `main` branch.
 
 Useful packaged commands:
 
@@ -54,10 +54,10 @@ npx copilot-usage-studio --help
 
 The CLI requires Node.js 22.5 or newer because optional VS Code `state.vscdb` enrichment uses Node's built-in SQLite support.
 
-Before registry publication, use the repository flow:
+For development or the current GitHub source, use the repository flow:
 
 ```bash
-git clone <repo-url>
+git clone https://github.com/fortunes-guardian/copilot-usage-studio.git
 cd copilot-usage-studio
 npm install
 npm start
@@ -76,7 +76,7 @@ npm run test:scripts
 npm run build
 ```
 
-Release copy should describe the app as a local Copilot usage debugger for VS Code. The strongest promise is: "VS Code already logs useful usage data locally; this app makes it understandable for developers who do not have billing-console access."
+Release copy should describe the app as a local Copilot usage inspector for VS Code, now available as a local VSIX preview. The strongest promise is: "VS Code already logs useful usage data locally; this app makes it understandable for developers who do not have billing-console access."
 
 ### Packaged Data Location
 
@@ -88,7 +88,72 @@ The packaged CLI stores its current normalized snapshot outside the npm installa
 
 The npm tarball contains the compiled UI, scanner, pricing table, and runtime code. It must never contain `public/data/sessions.json` or any other developer's imported session data.
 
-### Publishing
+## Automated Releases
+
+GitHub Actions is the release control plane:
+
+- `.github/workflows/ci.yml` runs the full release gate and packages a VSIX artifact for every pushed branch, plus pull requests to `main`.
+- `.github/workflows/release.yml` runs automatically for version tags such as `v0.1.1`, with a manual existing-tag mode for repair and backfill.
+- The release workflow verifies that the tag matches `package.json`, runs the release gate, packages the VS Code extension VSIX, generates release notes from `CHANGELOG.md`, and creates the matching GitHub Release.
+- After maintainer smoke testing and Marketplace credentials are configured, public extension releases should be published to the VS Code Marketplace so users can install without manually downloading a VSIX.
+- A failed workflow can be rerun safely: an existing npm version is accepted only when its published `gitHead` matches the exact tagged commit. Conflicting or unverifiable versions are refused.
+- New versions must pass the full release gate before publication. An exact-commit backfill of an already-published historical version skips its old test suite and only repairs the missing GitHub Release.
+
+This keeps GitHub, release artifacts, release notes, and the source tag tied to the same commit. Ordinary pushes never publish.
+
+### Branch Validation
+
+For feature work, push the branch and let CI run:
+
+```bash
+git push -u origin your-branch
+```
+
+The CI run proves the npm app and VS Code extension package from that branch. Download the `copilot-usage-studio-vsix` artifact from the workflow run when you want to test exactly what GitHub built. For a solo-maintainer flow, a pull request is useful for review and history, but branch CI is enough for a pre-merge smoke test.
+
+### One-Time npm Setup
+
+Commit and push the workflow files first, then configure npm Trusted Publishing for the existing `copilot-usage-studio` package:
+
+1. Open the package settings on npm and add a GitHub Actions trusted publisher.
+2. Set organization or user to `fortunes-guardian`.
+3. Set repository to `copilot-usage-studio`.
+4. Set workflow filename to `release.yml`.
+5. Allow the `npm publish` action.
+6. Leave the environment blank unless the workflow is later changed to use a protected GitHub environment.
+
+The workflow uses GitHub's OIDC identity, so no long-lived `NPM_TOKEN` repository secret is required. npm automatically adds provenance for a public package published from a public repository through Trusted Publishing.
+
+### Publishing a Version
+
+Start from an up-to-date, clean `main` branch. Choose the semantic-version bump that matches the change:
+
+First, make sure `CHANGELOG.md` has a useful human summary under `Unreleased` or under the exact version heading you are about to publish. The GitHub Release body is generated from that curated changelog text, with commits included only as an audit trail.
+
+```bash
+git switch main
+git pull --ff-only
+npm run release:check
+npm version patch
+git push origin main --follow-tags
+```
+
+`npm version patch` updates both `package.json` and `package-lock.json`, creates a version commit, and creates an annotated `vX.Y.Z` tag. Use `npm version minor` for a backward-compatible feature release or `npm version major` for a breaking release.
+
+After the tag is pushed:
+
+1. Watch the **Release** workflow in GitHub Actions.
+2. Confirm the new version appears on npm.
+3. Confirm GitHub created a Release for the same tag.
+4. Confirm the release notes read well and include the curated highlights.
+5. Download the attached VSIX if the extension should be tested or shared.
+6. Run `npx copilot-usage-studio@X.Y.Z --version` from a clean directory as a final smoke test.
+
+If CI or release validation fails, fix the issue on `main` and publish a new version. Do not move or reuse a public release tag, and do not overwrite an npm version; both are immutable release coordinates.
+
+The workflow also has a manual **Run workflow** action with a required existing tag. Use this to repair or backfill the GitHub Release for an exact tag. For the already-published first version, ensure `v0.1.0` exists on GitHub, then run the workflow once with `v0.1.0`; it will verify npm's published `gitHead`, skip the historical release gate and npm publication, and create the missing GitHub Release.
+
+### Manual Emergency Fallback
 
 Run the full package gate:
 
@@ -102,7 +167,7 @@ Inspect the tarball list, confirm no local session data or absolute paths are pr
 npm publish --access public
 ```
 
-Publishing is an external release action and should not be automated from ordinary development commands.
+Use this only if Trusted Publishing or GitHub Actions is unavailable. The normal path is the tag-driven workflow above.
 
 If the browser shows updated markup with stale component styles, stop the dev server and restart it with a cache reset:
 
@@ -126,7 +191,7 @@ Then serve the generated `dist/` output with a small local static server.
 
 Why: Angular production output is just static assets plus the generated `public/data/sessions.json` copy. This is a good first packaging target because it avoids an app server and keeps the data model simple.
 
-Current build status: `npm run build` passes. There is still an initial bundle budget warning to clean up later; it does not block the local preview release.
+Current build status: `npm run build` passes. There are still Angular budget warnings for the initial bundle and `src/app/app.css`; they do not block the local preview release.
 
 For day-to-day development, use the in-app **Refresh** action. `npm run refresh:data` remains the explicit command-line scan plus verification path.
 
@@ -140,13 +205,38 @@ npm run runtime
 
 It listens on `http://127.0.0.1:4312/` by default and exposes:
 
-- `GET /api/status`: scan state, timestamps, last error, and session count
+- `GET /api/status`: scan state, timestamps, current progress, recent log lines, last error, and session count
+- `GET /api/logs`: bounded in-memory runtime logs and the local log-file path
 - `GET /api/sessions`: the current normalized in-memory `SessionData`
 - `POST /api/scan`: run a scan, persist the new snapshot, and return it
 - `GET /data/sessions.json`: compatibility route backed by the current in-memory snapshot
 
 The runtime seeds itself from `public/data/sessions.json` when needed, then keeps its live cache under `tmp/local-runtime/`. This avoids triggering an Angular development rebuild every time the user refreshes data. It serves cached data while a scan is running, and a failed scan does not replace the last valid snapshot.
 
+Runtime scans run in a child process. This keeps `/api/status` and `/api/logs` responsive even when a large VS Code profile is being imported or a workspace has unusually heavy local data.
+
+### Startup Diagnostics
+
+If the app appears stuck on startup, there are three places to inspect:
+
+1. The app loading screen shows the current scan step, recent runtime log messages, cached session count, and the runtime log-file path.
+2. The terminal running `npm start` or `npx copilot-usage-studio` prints scan progress such as discovered workspace folders and debug-log folder counts.
+3. The status endpoint can be queried directly:
+
+```bash
+npx copilot-usage-studio status
+```
+
+For packaged `npx` runs, the runtime log file is stored beside the local session cache:
+
+- Windows: `%LOCALAPPDATA%\Copilot Usage Studio\runtime.log`
+- macOS: `~/Library/Application Support/Copilot Usage Studio/runtime.log`
+- Linux: `${XDG_DATA_HOME:-~/.local/share}/copilot-usage-studio/runtime.log`
+
+For repository development with `npm start`, the log is written to `tmp/local-runtime/runtime.log`.
+
+The scanner is intentionally bounded. It scans known VS Code Copilot storage locations plus targeted `.github/instructions`, `.github/skills`, `.github/prompts`, and `.github/hooks` folders for the workspace. Recursive Markdown scans have depth and directory-count caps and skip common dependency/build folders such as `node_modules`, `.git`, `dist`, `build`, `target`, and virtual environments. It should not crawl arbitrary project directories.
+
 To build the production UI and serve the complete local app with one command:
 
 ```bash
@@ -183,9 +273,25 @@ Why: this keeps the project local and scriptable without committing to a desktop
 
 The shared scanner API, runtime, and npm executable are complete. The same runtime can be embedded by Electron later.
 
-## Future Option: VS Code Companion Extension
+## VS Code Companion Extension Preview
+
+A thin VS Code extension now calls the shared scanner from the local extension host and shows the existing UI in a webview. It remains a host, not a fork of the pricing and parsing logic.
+
+Build a local preview VSIX:
+
+```bash
+npm run vscode:package
+```
+
+Install it locally:
+
+```bash
+code --install-extension tmp/copilot-usage-studio-vscode-0.2.0.vsix --force
+```
+
+The extension exposes the full app inside VS Code: Usage, Sessions, Memory, Customizations preview, Compare, Insights, and Prices. The npm/browser host remains useful for development and fallback testing, but the extension is the primary product surface.
 
-A thin VS Code extension can call the shared scanner from the local extension host and show the existing UI in a webview. It should remain a host, not a fork of the pricing and parsing logic.
+The VSIX is a separate distribution artifact from the npm package. It is built from the same source tree. After Marketplace release is configured, the VS Code Marketplace should be the normal install route; `npx copilot-usage-studio` remains a development/fallback host.
 
 Why not move the whole product into an extension: keeping the scanner and analysis core editor-independent preserves a path to a desktop app and possible Visual Studio support if Visual Studio exposes equivalent local evidence later.
 

package/docs/pricing.md

@@ -17,10 +17,10 @@ https://docs.github.com/en/copilot/concepts/billing/usage-based-billing-for-orga
 Current version:
 
 ```text
-github-copilot-usage-pricing-2026-06-14
+github-copilot-usage-pricing-2026-07-05
 ```
 
-The source table says prices are per 1 million tokens. The committed snapshot was checked against GitHub Docs on June 14, 2026.
+The source table says prices are per 1 million tokens. The committed snapshot was checked against GitHub Docs on July 5, 2026.
 
 ## Where Pricing Lives
 
@@ -40,7 +40,7 @@ This should be a deliberate maintainer update, not a runtime web fetch.
 
 1. Open GitHub's official model pricing page and record the check date.
 2. Update `data/github-copilot-pricing.json`, including model availability, all token buckets, and request-size tiers.
-3. Keep tier thresholds machine-readable. Apply them per model call using normal plus cached input, never aggregated session tokens.
+3. Keep tier thresholds and raw-model aliases machine-readable. Apply tiers per model call using normal plus cached input, never aggregated session tokens.
 4. Update the pricing version and snapshot date.
 5. Add or update threshold boundary tests and verify that several smaller calls do not accidentally trigger a long-context tier.
 6. Run `npm run refresh:data` to recalculate the local development snapshot.

package/docs/scanner-api.md

@@ -26,7 +26,7 @@ import { scanVsCodeSessions } from './lib/scanner-api.mjs';
 const sessionData = await scanVsCodeSessions();
 ```
 
-The result is the normalized `SessionData` document consumed by the Angular UI. No file is created or changed.
+The result is the normalized `SessionData` document consumed by the Angular UI. It contains imported `sessions` plus a sibling `memories` collection for observed Copilot Markdown memories and plans. No file is created or changed.
 
 This is the intended path for:
 
@@ -42,23 +42,51 @@ This is the intended path for:
 const sessionData = await scanVsCodeSessions({
   roots: ['/custom/Code/User'],
   sqlite: true,
+  includeCustomizations: true,
   generatedAt: new Date(),
+  onProgress: (event) => console.log(event.message),
 });
 ```
 
 - `roots`: optional array of VS Code `User` directories or individual workspace-storage directories. Defaults to stable VS Code and VS Code Insiders paths for the current operating system.
 - `sqlite`: set to `false` to skip optional `state.vscdb` metadata enrichment. Debug-log token and usage import still works.
+- `includeCustomizations`: set to `false` to skip instruction/skill/prompt/hook/agent inventory and evidence matching. The VS Code extension normally leaves this enabled because it exposes the Customizations view.
+- `includeSystemCustomizations`: set to `true` to include customizations contributed by installed VS Code extensions or VS Code application extension folders. The default is `false` so startup focuses on user/repo customizations and avoids expensive evidence matching for system-provided skills.
 - `generatedAt`: optional `Date` or date-compatible value, primarily for deterministic hosts and tests.
 - `usdToEur`: legacy generated-contract conversion value. The product UI is USD-first and callers should normally leave this unset.
+- `onProgress`: optional callback for host diagnostics. It receives scan-stage events such as root discovery, workspace discovery, debug-log folder counts, memory indexing, and completion. Hosts should treat these as user-facing diagnostics, not stable analytics data.
 
 Duplicate roots are normalized and scanned once. Each call receives fresh ingestion diagnostics; counters and warnings do not leak from earlier scans in a long-running process.
 
 Only one scan may run at a time within one Node process. Hosts should debounce filesystem events and await the current scan instead of starting overlapping work.
 
+## Internal Scanner Modules
+
+The public host boundary remains `lib/scanner-api.mjs`, but the scanner implementation is being decomposed so large-profile performance issues are easier to diagnose.
+
+Current internal split:
+
+- `scripts/scanner-traversal.mjs`: VS Code user-data root discovery, workspace-storage entry discovery, bounded recursive file traversal, dependency/build-folder skips, and root normalization.
+- `scripts/scanner-workspace.mjs`: per-storage-entry orchestration for state DB enrichment, customization inventory/evidence, debug-log imports, chat-snapshot imports, memory imports, progress events, and per-entry diagnostics.
+- `scripts/scanner-customization-inventory.mjs`: bounded discovery of user, workspace, repo, and configured Copilot customization files without crawling arbitrary repositories.
+- `scripts/scanner-customization-evidence.mjs`: request-payload and side-file text matching for whether customization content is visible in local model-request logs.
+- `scripts/scanner-memory.mjs`: Copilot memory/plan Markdown import plus memory recall linking from debug-log tool events.
+- `scripts/scanner-session-parser.mjs`: Agent Debug Log and chat-snapshot session parsing, token/cache fields, model breakdowns, request payload summaries, trace events, source usage, and fallback chat estimates.
+- `scripts/scan-vscode-sessions.mjs`: scan lifecycle, diagnostics lifetime, SQLite enrichment, workspace aggregation, final normalized session-data assembly, CLI argument parsing, and JSON persistence.
+
+Traversal is intentionally separate because broad filesystem walking is the highest-risk performance path. The scanner should scan known VS Code Copilot storage plus targeted Copilot customization/memory roots; it must not crawl arbitrary repositories or home directories.
+
+Next decomposition targets:
+
+- pricing/token normalization
+- SQLite/state enrichment helpers
+
 ## Local Runtime Host
 
 `lib/local-runtime.mjs` is the first shared API host. It keeps the last valid `SessionData` snapshot in memory, serves it while scans run, and persists successful refreshes.
 
+The local runtime runs the scanner in a child process by default. This keeps the HTTP status/log endpoints responsive while large local VS Code profiles are being imported.
+
 The runtime intentionally keeps scanner and transport concerns separate:
 
 - the scanner knows how to read and normalize VS Code data
@@ -96,7 +124,7 @@ There is one parser and pricing implementation. Future hosts should not copy sca
 
 ## Privacy And Source Rules
 
-The API reads local VS Code Copilot storage and can encounter prompts, file paths, repository context, tool schemas, and tool results. Hosts must keep results local unless a user explicitly exports them.
+The API reads local VS Code Copilot storage and can encounter prompts, file paths, repository context, tool schemas, tool results, saved memories, and saved plans. Hosts must keep results local unless a user explicitly exports them.
 
 The API does not change evidence rules:
 
@@ -105,5 +133,6 @@ The API does not change evidence rules:
 - cached input remains separate from normal input and output
 - chat snapshots remain fallback data
 - SQLite is metadata enrichment, not a billing source
+- saved memory files are indexed as local artifacts; their presence does not prove they were recalled into a model request
 
-See [data-ingestion.md](data-ingestion.md), [debug-log-schema.md](debug-log-schema.md), and [pricing.md](pricing.md) for those contracts.
+See [data-ingestion.md](data-ingestion.md), [copilot-memory.md](copilot-memory.md), [debug-log-schema.md](debug-log-schema.md), and [pricing.md](pricing.md) for those contracts.

package/lib/cli.mjs

@@ -98,7 +98,21 @@ export async function runCli(args = process.argv.slice(2), dependencies = {}) {
   }
   if (options.command === 'status') {
     const fetchStatus = dependencies.fetch ?? globalThis.fetch;
-    const response = await fetchStatus(`http://${options.host}:${options.port}/api/status`);
+    const timeoutMs = Number(dependencies.statusTimeoutMs ?? 5000);
+    const signal = Number.isFinite(timeoutMs) && timeoutMs > 0 && typeof AbortSignal !== 'undefined'
+      ? AbortSignal.timeout(timeoutMs)
+      : undefined;
+    let response;
+    try {
+      response = await fetchStatus(`http://${options.host}:${options.port}/api/status`, { signal });
+    } catch (error) {
+      const timedOut = error instanceof Error && error.name === 'TimeoutError';
+      throw new Error(
+        timedOut
+          ? `Local runtime did not respond on ${options.host}:${options.port} within ${timeoutMs}ms.`
+          : `Could not reach local runtime on ${options.host}:${options.port}.`,
+      );
+    }
     if (!response.ok) {
       throw new Error(`Local runtime returned ${response.status}.`);
     }