@sandgarden/miranda 0.1.82 → 0.1.86

package/collector/stub.sh

@@ -44,15 +44,15 @@
 # now downloads the same release from "sandgardenhq/plugins" with the
 # "miranda-collector" prefix (#813). They stay placeholders rather than
 # literals so the release host can move without editing this file.
-BUILD_VERSION="9f7f592e18a1"
-RELEASE_TAG="collector-9f7f592e18a1"
+BUILD_VERSION="dfe686cb61ce"
+RELEASE_TAG="collector-dfe686cb61ce"
 RELEASE_REPO="sandgardenhq/plugins"
 ASSET_PREFIX="miranda-collector"
-CHECKSUM_DARWIN_ARM64="bea2b552aa21695580ce1f9a0718de064475260bdf830330b8047f0064c4e4b7"
-CHECKSUM_DARWIN_X64="3fe706eb9d77306f33d6550d20b7bb39a343349f64ad2b7476554111f3eb0415"
-CHECKSUM_LINUX_X64="a43d87711cae9c43462b1297d6780126cc792710ab056fed80959f43c5679724"
-CHECKSUM_LINUX_ARM64="e4824ceb3d4c937ef364f110835aeba6a533a17c90f46e262fea7dbb044c0729"
-CHECKSUM_WINDOWS_X64="e2d6b01fed9f350aeedab3a60840f07b7cbe4b596e0327687fa664339a99238c"
+CHECKSUM_DARWIN_ARM64="58b322fa26b3f2b7d2d6796d7f041b03916c78bc3fe34298157d812524697adb"
+CHECKSUM_DARWIN_X64="2de39f78f59bf4fe2482e75ccd182d30e2881400a1d3d662bcb376e54a24e1af"
+CHECKSUM_LINUX_X64="ee4f23586c6a96b86c3a1bcc98b37568c8de3e459cd1c1616096cbe3d8c30d37"
+CHECKSUM_LINUX_ARM64="aa93bc71849dd295817d907f20865bdda1560145b46fbcc850b6b67293bc1a62"
+CHECKSUM_WINDOWS_X64="e4024913af817202bc83e07fb3527ce6fb8ad75527c593e64c49118c11fa63ba"
 
 # A download lock older than this is a downloader that died mid-run: take it
 # over (mirrors the collector's sweep-lock staleness cutoff).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandgarden/miranda",
-  "version": "0.1.82",
+  "version": "0.1.86",
   "type": "module",
   "description": "Miranda OpenCode plugin — token-usage tracking skill + the gloria.dev MCP server's scoped /miranda tools.",
   "main": "index.js",

package/skills/setting-up-usage-tracking/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setting-up-usage-tracking
-description: Use when installing the Miranda plugin into a repo ("set up token tracking", "enable usage tracking", "install miranda"), when a repo is missing .miranda/USING-MIRANDA.md or the miranda section in CLAUDE.md/AGENTS.md, or after a Miranda plugin update to refresh a stale doc — copies the canonical USING-MIRANDA.md agent doc into the repo, wires an evergreen Miranda section into the agent instruction files (with the user's permission), and enrols this machine for usage collection. Idempotent; safe to re-run.
+description: Use when installing the Miranda plugin into a repo ("set up token tracking", "enable usage tracking", "install miranda"), when a repo is missing .miranda/USING-MIRANDA.md or the miranda section in CLAUDE.md/AGENTS.md, or after a Miranda plugin update to refresh a stale doc — copies the canonical USING-MIRANDA.md agent doc into the repo, wires an evergreen Miranda section into the agent instruction files (with the user's permission), enrols this machine for usage collection, and registers the current repository as a Miranda project if it isn't one. Idempotent; safe to re-run.
 ---
 
 # Setting Up Usage Tracking
@@ -20,10 +20,14 @@ gets collected. Two files carry that:
    releases; only the doc does.
 
 Then, once those are wired, enrol this machine so the collector daemon the
-Miranda plugin installs actually starts reporting usage.
+Miranda plugin installs actually starts reporting usage, and make sure this
+repository is a Miranda project — the collector attributes a session to a
+project only when the session's `origin` remote matches one, so an
+unregistered repository's spend all lands in **Unassigned**.
 
 Never modify the user's files without showing them exactly what will change
-and getting a yes first.
+and getting a yes first. Registering the repository writes no file, and is
+done without asking (step 6).
 
 ## What the collector reports
 
@@ -44,7 +48,7 @@ they are consenting to.
 - `model_request`: the token counts already reported today
 - `tool_call`: tool name, argument names, repo-relative file path, and a shell command's first word only, plus the names of any wrappers a hook added to it before it ran (such as `rtk`)
 - `tool_result`: error flag, size, exit code and test counts, never the output
-- `project_facts`: manifest and instruction file names, sizes and hashes
+- `project_facts`: manifest and instruction file names, sizes and hashes, and the MCP server names the repo's agent config files declare
 - `skill_invoked`: skill name and whether it came from a plugin, the project, or the user
 - `subagent_spawned`: subagent type, model override and whether it ran in the background, never its prompt
 - `plan_mode`: entering or leaving plan mode, never the plan
@@ -52,6 +56,7 @@ they are consenting to.
 - `vcs_event`: commit, push, PR create or merge, or rebase, with PR and issue numbers only, never a branch, message or remote
 - `hook_fired`: hook name, the first word of the hook's own command (such as `rtk`), and whether it blocked, never its arguments or output
 - `mcp_tool_call`: MCP server and tool name, never arguments or results
+- `machine_facts`: the MCP server names the session's agent has configured on the machine, and whether each is on, never their commands, URLs, headers or env
 
 ## The instruction-file section
 
@@ -121,7 +126,7 @@ commitment the team has made, not a suggestion.
     → the deprecated `GLORIA_HOME` → `$XDG_CONFIG_HOME/sandgarden` →
     `~/.config/sandgarden`). `daemon status` always exits 0, so "not
     enrolled" is not an error. Treat this as extra detail for the report in
-    step 6, not as the enrolment test — the `config.json` check above is the
+    step 7, not as the enrolment test — the `config.json` check above is the
     one that has to work on every machine.
 
 ### 2. Propose and ask permission — once
@@ -137,7 +142,9 @@ yes/no. Cover only the actions actually needed, e.g.:
 - enrol this machine for usage tracking, if it is not already, saying what
   the collector reports (see "What the collector reports").
 
-If everything is already current, say so and skip to step 6. If the user
+If everything is already current, say so and skip to step 6.
+Registering the repository is not part of this yes/no — step 6 does it
+without asking. If the user
 declines the file edits, stop — do not partially apply.
 
 ### 3. Write the doc
@@ -272,15 +279,98 @@ this machine's local session stores whether or not any agent plugin fires, so
 no further wiring is needed. See `USING-MIRANDA.md`'s "Codex, OpenCode, and
 Cursor" section for per-agent notes.
 
-### 6. Report
+### 6. Register this repository as a project
+
+Run this after step 5, whichever enrolment path ran — and also when steps 2–5
+had nothing to do. Do it **without asking**: the developer is setting up
+tracking for exactly this repository, and registering it is the only way its
+spend stops landing in Unassigned. Use the `miranda` MCP tools only.
+
+1. **Read the remote.** At the repo root (`git rev-parse --show-toplevel`),
+   run:
+
+   ```sh
+   git remote get-url origin | sed -E 's#://[^/@]*@#://#'
+   ```
+
+   The `sed` drops any userinfo (`user:token@`) before the URL is printed: an
+   `https` remote can carry a credential, and it must never reach the
+   transcript, a tool argument or the report. Use `origin` and nothing else —
+   it is the only remote the collector reads. If this isn't a git repository,
+   or the command prints nothing on stdout (no `origin` remote — git's
+   `error: No such remote` goes to stderr), skip the rest of step 6 and say
+   why in the report (e.g. "this repository has no `origin` remote, so there
+   is no URL a project could match").
+
+2. **Normalize it** the way the server does, so the comparison means what
+   ingest means:
+   - scp-like SSH, `git@host:owner/repo.git` → `https://host/owner/repo`;
+   - `ssh://`, `git://` and `git+ssh://` URLs → `https://` on the same host
+     (port included) and path; `http://` and `https://` keep their scheme;
+   - drop any userinfo left, then a trailing `.git` (and any `/` after it),
+     then any trailing `/`.
+
+   Change nothing else — not even letter case.
+
+3. **Look for a match.** Call `list_projects`, normalize each project's
+   `repoUrl` the same way (older rows can carry a trailing `/` or `.git`), and
+   compare exactly, case-sensitive — ingest matches the same way, so a
+   case-only difference is not a match. If a project matches, name the
+   existing project — its name and slug (all of them, if more than one
+   matches) — say spend from this repository is already attributed to it, and
+   register nothing.
+
+4. **Register when nothing matches.** Call `register_project` with
+   `{ "project": { "slug": …, "name": …, "repoUrl": <normalized URL> } }`:
+   - `name` — the repository name: the last path segment of the normalized
+     URL (`https://github.com/sandgardenhq/gloria.dev` → `gloria.dev`);
+   - `slug` — that name lowercased, every run of characters outside `a-z0-9`
+     replaced by `-`, leading and trailing `-` trimmed (`gloria-dev`).
+
+   `register_project` **upserts by slug**: sending a slug some other project
+   already has overwrites that project's name and repository. So if
+   `list_projects` already has the slug — whatever its `repoUrl`, set or not —
+   or the slug came out empty, use `<owner>-<repo>` built the same way
+   (`sandgardenhq-gloria-dev`). `<owner>` is the path segment before the
+   repository name (for `https://gitlab.com/group/sub/repo`, `sub`). If that is
+   taken too, append a number to it — `<owner>-<repo>-2`, `-3`, … — until it
+   is free. Slugs can't be changed later, so never guess past this rule.
+
+5. **Report what happened** in step 7, from the result's `project` and
+   `backfill`:
+   - the `slug` it registered under (and the name, when it isn't the same as
+     the slug);
+   - `backfill.status` `"ran"` with `sessionCount` above 0 — that many earlier
+     sessions moved from Unassigned onto the project, worth `spendMicros` ÷
+     1,000,000 dollars (round to cents), the earliest from `earliestSessionAt`
+     (Unix seconds; show it as a date). When `unpriced` is true, some of that
+     spend has no price yet, so the dollar figure is a lower bound — say so;
+   - `"ran"` with `sessionCount` 0 — there was no earlier Unassigned spend
+     from this repository to move;
+   - `"failed"` — the project is saved, but its earlier spend didn't move;
+     sessions from now on are attributed to it;
+   - `"skipped"` — nothing moved;
+   - in every case, spend from more than 80 days before today stays in
+     Unassigned.
+
+If `list_projects` or `register_project` fails with a transient error (a
+dropped connection, a timeout), retry it once. If it still fails, or the
+`miranda` MCP server isn't connected, or the call returns an error — say so,
+with the error, and carry on to the report. It doesn't undo the file edits or the enrolment.
+
+### 7. Report
 
 Summarize what changed (files created/updated, section inserted where,
-usage tracking configured or already present) and suggest committing the
-changes, e.g. `chore: wire miranda agent doc into instruction files`.
+usage tracking configured or already present, the project registered or
+matched — or why the step was skipped — with what step 6 moved) and suggest
+committing the changes, e.g. `chore: wire miranda agent doc into instruction
+files`.
 
 ## Idempotency rules
 
 - Re-running with identical content is a no-op; say "already current".
+- Re-running in a repository that is already a project registers nothing:
+  step 6 finds the match and names it.
 - Marker blocks are always replaced in place, never duplicated. If a file
   somehow contains multiple marker blocks, replace the first and remove the
   rest, and mention it.

package/skills/setting-up-usage-tracking/USING-MIRANDA.md

@@ -13,7 +13,8 @@ Miranda is available two ways, and both apply to you:
   `get_my_effectiveness`, `get_my_workflow`, `get_my_tracking_status`,
   `assign_my_session_work_item`, the managers-only `get_team_effectiveness`,
   plus the shared
-  `get_info`/`register_project`/`put_project_github_info` — the same rows the
+  `get_info`/`list_projects`/`register_project`/`put_project_github_info` —
+  the same rows the
   `gloria` server exposes, since Miranda and gloria share one database).
 - **The usage-collector hooks** installed with the Miranda plugin (Claude
   Code, Codex, OpenCode) — they run automatically once the collector's
@@ -120,6 +121,28 @@ flight. The collector's `gloria-usage session` subcommand will answer that
 locally, with no round-trip, once it ships; until then, say the current
 session's cost isn't available yet rather than estimating it.
 
+## When this repository isn't a project
+
+Miranda attributes a session to a project only when the session's `origin`
+remote matches a registered project's `repoUrl`; everything else lands in
+**Unassigned**, where no per-project or per-issue figure can see it. So when a
+Miranda tool result shows this repository isn't a project — `list_projects`
+has no project whose `repoUrl` matches this repository's `origin`, or
+`get_my_tracking_status` or `get_my_spend` puts this repository's sessions in
+Unassigned — register it, **without asking**. Registering is part of tracking
+this repository, which the team has already adopted.
+
+Follow the `setting-up-usage-tracking` skill's "Register this repository as a
+project" step: read `origin` with
+`git remote get-url origin | sed -E 's#://[^/@]*@#://#'` (the `sed` keeps a
+token embedded in the remote out of the transcript), normalize it (SSH forms
+to `https://`, no userinfo, no `.git` or trailing `/`), compare it against
+every project's `repoUrl` normalized the same way, and when nothing matches, call `register_project` with the repository's name
+and a slug no existing project has. Then tell the user the slug and what the
+result's `backfill` moved out of Unassigned (sessions, dollars, earliest
+session). Spend older than 80 days stays in Unassigned. No `origin` remote
+means nothing to match — say so and move on.
+
 ## Setting up usage tracking
 
 The Miranda plugin ships hooks (Claude Code, Codex, OpenCode) that transmit
@@ -138,8 +161,13 @@ Reads need `inventory:read` (any member); writes need `inventory:write`.
 
 - `get_info` — org id/name/slug. Cheap; call it first when you need org
   context or to check the `miranda` MCP server is reachable.
+- `list_projects` — every project in the org, with its `repoUrl`. How you
+  tell whether this repository is a project yet.
 - `register_project`, `put_project_github_info` — register this repo as a
-  gloria.dev/Miranda project (the same rows either server writes).
+  gloria.dev/Miranda project (the same rows either server writes). Upserts by
+  slug, so never send a slug another project already has. When it gives a
+  project a `repoUrl`, its `backfill` reports the repository's earlier
+  Unassigned spend that moved onto it.
 - `tag_session_work_item` — declare the GitHub issue this session is working
   on (bare issue number, `gh:482`, or a full issue URL). Session-local — it
   writes only to this session's own transcript, never the database — the