greprag 5.16.1 → 5.17.0

package/skill/commander/SKILL.md

@@ -17,141 +17,113 @@ description: |
   session to take this DM".
 metadata:
   author: travsteward
-  version: "2.0.0"
+  version: "3.0.0"
   repository: https://github.com/travsteward/greprag
 license: MIT
 ---
 
 # Commander — Discord DM bridge
 
-The operator commands an open Claude session from Discord. The Discord side is the *channel*; "commander" is the *role* the operator inhabits when the DMs land.
+The operator commands an open Claude session from Discord. Pairing links the account; **handoff** pins the operator's DMs to one session so the thread follows them off the desk.
 
-The agent runs `greprag discord me` to learn the current state, then branches into pair / handoff / status. Everything else is one shell command per branch.
+**Commander writes the routing pin. It does not arm the watcher.** Every greprag session already keeps a session-scoped inbox watcher live — the detection-gated `notify` hook re-arms it on any unarmed turn (`adr/session-id-awareness.md`). A Discord DM is filed with `to_session_id = this session`, which that auto-armed watcher already delivers (its filter is `to_session_id = session OR NULL`). So **session handoff is one Bash call that writes the pin and exits** — no Monitor, no second watcher. Only **orchestrator** mode arms (the session auto-arm is session-scoped; portfolio-wide eyes need a tenant-wide stream).
 
-## Step 1 — Get the state
+## Step 1 — State first
 
 ```bash
 greprag discord me
 ```
 
-Parse the JSON. Then **default to the handoff flow** unless the user's message is an explicit status query.
+Parse the JSON, then **default to handoff** unless the message is an explicit status query:
 
-- **Default action:** the user invoked `/commander` (or any handoff trigger phrase). They want a handoff armed. Branch by pairing state:
-  - `paired: false` → run **pair flow** (Step 2), then continue into **handoff flow** (Step 3) once paired.
-  - `paired: true` and `handoff === null` → run **handoff flow** (Step 3) immediately.
-  - `paired: true` and `handoff !== null` → the pin is already live. Print **status with handoff details** (Step 5), then ask whether to re-arm to a different session or leave it alone.
-- **Status-only branch:** ONLY skip the handoff flow when the user's message is an explicit status query — "am I paired?", "commander status", "what's my discord state?", or a direct request to inspect without arming. In that case go straight to Step 5.
+- `paired: false` → **pair** (Step 2), then **handoff** (Step 3).
+- `paired: true`, `handoff === null` → **handoff** (Step 3).
+- `paired: true`, `handoff !== null` → pin already live: print **status** (Step 5), then ask whether to re-arm to a different session or leave it.
+- Explicit status query ("am I paired?", "commander status", "what's my discord state?") → **status** (Step 5) only.
 
-The bare slash-command invocation `/commander` is itself a handoff trigger. Do not treat it as ambiguous; arm the watcher. If the user wanted status only, they'd say so.
+Bare `/commander` is itself a handoff trigger — arm the pin, don't treat it as ambiguous. If the user wanted status only, they'd say so.
 
-## Step 2 — Pair flow (only if not paired)
+## Step 2 — Pair (only if `paired: false`)
 
 ```bash
 greprag discord pair
 ```
 
-Prints the 6-char code. Tell the user verbatim:
+Prints a 6-char code. Tell the user verbatim:
 
 > DM `@greprag` on Discord: `/pair <CODE>` (expires in 15 min).
 
-When they confirm the bot replied with "Paired," re-run `greprag discord me` to verify, then continue. If the user wanted a handoff (their original request mentioned stepping away), proceed to Step 3 once paired.
+On "Paired" confirmation, re-run `greprag discord me` to verify, then continue to Step 3 if a handoff was intended.
 
-## Step 3 — Handoff flow (the killer feature)
+## Step 3 — Handoff (write the pin)
 
-Trigger: user said anything implying "I'm leaving the desk and want this thread to follow me to Discord" — *step away*, *continue on phone*, *handoff*, *DM me*, *afk*, *I'll be walking*.
+Resolve the session id (8-hex, from the SessionStart hook) and project (current anchor, or `--project <name>`).
 
-Resolve the session id from the SessionStart hook's `additionalContext` (8-hex form). Resolve the project name from the current anchor (`greprag project-id`'s sibling lookup, or the explicit `--project` flag).
+### Session handoff (default) — one Bash call, no Monitor
 
-### Two modes — pick by session role
-
-- **Session handoff (default).** This session is a focused per-project session. The watcher only surfaces inbox events for *this* `(project, session)`. Use when you're deep in one project's work.
-- **Orchestrator handoff** (`--orchestrator`). This session is the user's portfolio brain — `/business-advisor` or any `/<name>-advisor` is loaded, or the project is named `orchestrator` / `business` / a portfolio repo. The watcher is **tenant-wide**: this session sees inbox traffic from every project under the tenant. The DM routing pin still points to *this* session, so the user's DMs land here, but the agent has portfolio-wide eyes.
+```bash
+greprag discord handoff --session <8-hex> --project <name> --ttl 60 --no-watch
+```
 
-Detect: if `/business-advisor` is loaded, or the project name suggests orchestrator-class, default to `--orchestrator`. Ask the user if ambiguous.
+`--no-watch` writes the server-side pin (`active_project_id`, `active_session_id`, `active_expires_at`) and fires the confirmation DM, then exits. The DMs are delivered by this session's already-live auto-armed watcher — commander adds nothing.
 
-### Arm the watcher
+Tell the user: *"Handoff pinned for 60 min. Reply on Discord — your messages route to this session."*
 
-Under **Monitor with `persistent: true`**, wrapped in the `while true` restart loop so a process death (npm install mid-session, network blip, supervisor bug) auto-recovers.
+> Safety net: if `greprag inbox watchers` shows no watcher for your 8-hex (auto-arm disabled, or it died and the next turn hasn't re-armed yet), arm one under **Monitor (persistent:true)**: `while true; do greprag inbox watch --session <8-hex> --json; echo "[restart]" >&2; sleep 1; done`.
 
-**Session handoff (default):**
+### Orchestrator handoff (`--orchestrator`) — the only mode that arms
 
-```bash
-greprag discord handoff --session <8-hex> --project <name> --ttl 60 --no-watch && \
-while true; do
-  greprag inbox watch --project <name> --session <8-hex> --json --no-supervise
-  echo "[wrapper] watcher exited, restarting in 1s" >&2
-  sleep 1
-done
-```
+This session is the user's portfolio brain (`/business-advisor` or any `/<name>-advisor` loaded; project named `orchestrator` / `business` / a portfolio repo). The DM pin still routes here, but the watcher is **tenant-wide** — it sees inbox traffic from every project under the tenant, which the session-scoped auto-arm does not cover. Detect from loaded skills / project name; ask if ambiguous.
 
-**Orchestrator handoff:**
+Run under **Monitor (persistent:true)**, wrapped so a process death auto-recovers:
 
 ```bash
 greprag discord handoff --session <8-hex> --project <name> --ttl 60 --orchestrator --no-watch && \
 while true; do
-  greprag inbox watch --json --no-supervise
+  greprag inbox watch --json
   echo "[wrapper] watcher exited, restarting in 1s" >&2
   sleep 1
 done
 ```
 
-Two halves on purpose:
-1. `discord handoff --no-watch` writes the pin server-side (`active_project_id`, `active_session_id`, `active_expires_at`) and fires the confirmation DM to the user's phone. Returns immediately. `--orchestrator` only changes downstream behavior in the help text and skill detection; the pin itself is identical.
-2. The `while true` loop tails the inbox via SSE. Each line printed = one event landing as a Monitor notification. Scope differs: session-filtered (default) vs. tenant-wide (orchestrator).
+The pin comes from `discord handoff --no-watch`; the tenant-wide scope comes from the unfiltered `inbox watch --json`. (The per-turn auto-arm may also add a session-scoped watcher — harmless, it's a subset of the tenant-wide stream.)
 
-**Never use the bare `greprag discord handoff` form without `--no-watch` for production handoff.** It self-streams, but a process death (e.g. `npm i -g greprag@latest` from another shell wipes the install dir) takes the watcher down with no restart. The wrapped two-step is the resilient form.
+Tell the user: *"Orchestrator pinned for 60 min. I now see inbox events across all your projects. DM me 'roundup' or 'anything happening on <project>?' to query, or just chat — your messages land here."*
 
-Tell the user (session mode): "Handoff pinned for 60 min. Reply on Discord — your messages route to this session."
-Tell the user (orchestrator mode): "Orchestrator pinned for 60 min. I now see inbox events across all your projects. DM me 'roundup' or 'anything happening on <project>?' to query, or just chat — your messages land here."
+## Step 4 — Reply to inbound DMs
 
-## Step 4 — Replying to inbound DMs
-
-Each Monitor notification carries the full event payload: `body` is the user's message text, `references.discord.snowflake` is their Discord ID, and `references.discord.emergency_route` is non-null when the bot auto-routed an unassigned DM here (see Step 4b).
-
-Send your reply via the CLI:
+Each watcher event carries the payload: `body` (message text), `references.discord.snowflake` (their Discord ID), `references.discord.emergency_route` (non-null when auto-routed — see Step 4b).
 
 ```bash
 greprag send --to discord:<snowflake> "your reply text"
 ```
 
-The CLI uses Node fetch (UTF-8 native) — em-dashes, curly quotes, emoji all render correctly. **Do NOT use curl from bash on Windows** for Discord sends — the local code page (Win-1252) mangles non-ASCII bytes into `?` on the user's phone.
-
-**Voice-note DMs.** When the operator records a voice note instead of typing, the gateway transcribes it via Gemini before the inbox event reaches you. The `body` will be prefixed with `[voice]` (e.g. `[voice] step away for a bit`), or with `[voice transcription failed: ...]` if Gemini erred — in that case, ask the operator to re-record or fall back to the original audio URL in `references.discord.voice_attachments`. Reply path is unchanged: always text, via `greprag send --to discord:<snowflake>`.
-
-## Step 4b — Emergency-routed DMs (self-identify before answering)
-
-If `references.discord.emergency_route` is non-null, this session was auto-linked because no handoff pin was active. The user may have meant to reach a different session. **Open your first reply by self-identifying** so the operator can redirect if needed.
+The CLI uses Node fetch (UTF-8 native). **Never `curl` from bash on Windows** for Discord sends — the local code page (Win-1252) mangles non-ASCII into `?` on the user's phone.
 
-Example first reply:
+**Voice-note DMs.** The gateway transcribes before the event reaches you; `body` is prefixed `[voice]` (or `[voice transcription failed: ...]` — then ask for a re-record, or fall back to `references.discord.voice_attachments`). Reply path unchanged: text, via `greprag send`.
 
-> Picked this up in `<project-name>` / session `<session-8hex>` (no handoff was active, so I'm the most-recently-active armed session). Auto-pin is 10 min; it extends to 30 once you reply again. Want to redirect? `/commander handoff` from another session, or just say "redirect to <project>".
+Long turn (drafting >10s)? Refresh the indicator: `greprag discord typing` (silent on success; shows "GrepRAG is typing…" for ~10s). Reply >2000 chars → split on paragraph boundaries with continuation markers.
 
-How the bot chose this session: among all armed session-scoped watchers under your tenant, it picks the **most-recently-active** one — ranked by `max(last turn end, arm time)` — so a session that just finished a turn (idle, waiting) outranks one grinding a long task or gone dark. The auto-pin starts at a **genuine 10-min leash**, so one stray DM into the wrong session self-heals fast if you go quiet; your *next* DM (pin now live) extends it to ≥30 min so a real back-and-forth keeps flowing here. If the picked session turns out to be dead — or nothing is armed at all — the bot replies that your message is filed and will be delivered the moment a session reconnects (it never vanishes), and clears the dead auto-pin so the next DM re-runs the router.
-
-For long agent turns where you're drafting >10s, refresh the typing indicator between work steps:
-
-```bash
-greprag discord typing
-```
+## Step 4b — Emergency-routed DMs (self-identify first)
 
-Silent on success. Tells Discord to show "GrepRAG is typing…" for another 10s.
+`references.discord.emergency_route` non-null = this session was auto-linked because no handoff pin was active; the user may have meant another session. **Open the first reply by self-identifying** so they can redirect:
 
-If the reply exceeds 2000 chars (Discord's hard limit), split on paragraph boundaries and send multiple messages with continuation markers.
+> Picked this up in `<project>` / session `<8-hex>` (no handoff was active, so I'm the most-recently-active armed session). Auto-pin is 10 min; it extends to 30 once you reply again. Redirect? `/commander handoff` from another session, or say "redirect to <project>".
 
-## Step 5 — Status (when paired with no handoff intent, or to inspect)
+How the bot chose: among armed session-scoped watchers under the tenant, it picks the **most-recently-active** (ranked by `max(last turn end, arm time)`), so an idle just-finished session outranks one grinding a long task. The 10-min leash self-heals a wrong-session DM fast; the next DM (pin now live) extends to ≥30 min. If the picked session is dead or nothing is armed, the bot files the message (delivered when a session reconnects) and clears the dead auto-pin so the next DM re-runs the router.
 
-Print verbatim:
+## Step 5 — Status (paired, no handoff intent, or to inspect)
 
 ```
 Discord pairing:
-  Tenant:        travis (or whatever me.snowflake points to)
+  Tenant:        <me.snowflake's tenant>
   Default route: <me.project_name> (project_id <me.project_id>)
   Snowflake:     <me.snowflake>
   Paired at:     <me.paired_at>
   Last DM in:    <me.last_seen_inbound_at or "(never)">
 ```
 
-If `handoff !== null`:
+If `handoff !== null`, append:
 
 ```
 Active handoff pin:
@@ -164,24 +136,24 @@ Offer: *"Run `greprag discord unhandoff` to clear the pin and revert DMs to defa
 
 ## Orchestrator-mode interaction rules
 
-These apply only when handoff was armed with `--orchestrator`. The orchestrator is a *passive observer* of tenant-wide inbox traffic, NOT a forwarder.
+Apply only under `--orchestrator`. The orchestrator is a *passive observer* of tenant-wide traffic, NOT a forwarder.
 
-- **NEVER proactively DM the user.** The tenant-wide stream feeds the agent's context. Events accumulate silently. Do not surface them as DMs unless the user has explicitly asked or you're fulfilling a standing order.
-- **NEVER call plain `greprag inbox`.** The list endpoint defaults to `autoMarkRead: true`, which burns the unread state for recipient sessions. Use **`greprag inbox --peek`** (non-mutating) when you need to inspect historical messages, or rely on the Monitor stream's accumulated context.
-- **Pull on demand.** When the user DMs "roundup" / "what's been happening?" / "anything on <project>?", reconstruct from your accumulated Monitor events. If your context window has rotated, `greprag inbox --peek --all` (with optional `--project <name>`) is the safe retrieve.
-- **Standing orders.** When the user says "ping me when <X> happens" / "let me know when chip <id> reports done," remember the directive in working context. On each Monitor event, scan against directives. On match, DM the user once and drop the directive.
-- **Intervention.** When the user directs you to act on another project ("pause paybot's webhook chip"), look up the live session via `greprag inbox watchers`, then send the directive: `greprag send --to <handle>@greprag.com/<session-8-hex> "pause"`. That target session's own watcher fires the directive into its agent's turn.
-- **Discovery.** `greprag inbox watchers` lists currently-attached watchers under your tenant — every live session that has a watcher armed. Use it when the user references a project by name and you need the session id to message into.
+- **Never proactively DM the user.** Events feed your context silently; surface them only on explicit ask or a standing order.
+- **Never call plain `greprag inbox`** — its list defaults to `autoMarkRead: true`, burning recipient sessions' unread state. Use `greprag inbox --peek` (non-mutating) to inspect history, or rely on the accumulated watcher stream.
+- **Pull on demand.** On "roundup" / "anything on <project>?", reconstruct from accumulated events; if context rotated, `greprag inbox --peek --all [--project <name>]`.
+- **Standing orders.** "Ping me when <X>" → hold the directive in working context, scan each event, DM once on match, drop it.
+- **Intervention.** "Pause paybot's webhook chip" → find the live session (`greprag inbox watchers`), then `greprag send --to <handle>@greprag.com/<session-8hex> "pause"` — that session's own watcher fires it into its turn.
+- **Discovery.** `greprag inbox watchers` lists live armed sessions under the tenant — use it to resolve a project name to a session id.
 
-## Hard rules (all modes)
+## Hard rules
 
-- **Don't auto-handoff without user intent.** If the user just asked "am I paired?", show status — don't arm a Monitor.
-- **Always use the wrapped form** in production. The bare `discord handoff` is for testing only.
-- **Send replies via the CLI**, not curl. UTF-8 correctness, parser correctness, and the success-print all break in subtle ways otherwise.
-- **Never `npm i -g greprag@latest`** from a session with a running handoff watcher — it kills the watcher mid-stream. Either land the upgrade before arming, or stop the Monitor first.
-- **Pin scope is one snowflake → one session at a time.** A new handoff in another session supersedes the prior one silently. Orchestrator-mode does NOT change this — the pin is still one-at-a-time.
+- **Status query → status, not arm.** "Am I paired?" shows state; it never writes a pin.
+- **Session handoff writes the pin only** — the auto-arm hook owns the watcher. **Orchestrator is the sole arming path** (tenant-wide, wrapped under Monitor).
+- **Replies via the CLI, not curl** — UTF-8, parser, and success-print all break otherwise.
+- **Pin scope: one snowflake → one session at a time.** A new handoff supersedes the prior one silently; orchestrator mode does not change this.
+- **In orchestrator mode, don't `npm i -g greprag@latest`** while the tenant-wide Monitor watcher runs — it kills the watcher mid-stream. Land the upgrade first, or stop the Monitor.
 
 ## Related skills
 
-- `/greprag` — broader greprag setup (memory, inbox, corpus). Step 5g there carries the same handoff guidance for sessions invoked through greprag-as-orchestrator.
-- The `discord-notify` skill (separate, global) sends one-off Discord webhook pings for attention. Not related to this skill — that's a webhook, this is a paired DM bridge.
+- `/greprag` — broader greprag setup (memory, inbox, corpus); carries the same handoff guidance for orchestrator-class sessions.
+- `discord-notify` (separate global skill) sends one-off webhook pings for attention — a webhook, not this paired DM bridge.

package/skill/greprag/SKILL.md

@@ -70,13 +70,17 @@ Per-project flag flips (turn off recaps here, etc.): `docs/per-project-flags.md`
 
 ## Step 3 — Memory access (when configured)
 
-Two access patterns — pick by intent.
+Two access patterns. They have OPPOSITE biases, so pick by intent — don't default to one.
 
-**A. Search by topic** — when the operator references a past problem, bug, decision, or topic. Reach for this first.
+- **Recent / open-ended** ("what did we do", "catch me up", "this week", "where did we leave off") → **recap or daily**. Sorted by time; immune to lexical noise.
+- **Specific old bug / decision / topic** → **search**.
+- **Search came back weak or doc-heavy** (low scores, or the hits are skill/chip boilerplate) → do NOT keep rephrasing. A topic-grep can't fix a recency problem. Switch to the chronological pull, or narrow with `--shape daily`. The CLI prints this hint for you when it detects it.
+
+**A. Search by topic**
 ```bash
 greprag memory search "<query>"
 ```
-Query syntax is `websearch_to_tsquery`: AND is default, `OR` explicit, `"phrases"` quoted, `-negation` drops terms. Prints ranked hits (top 5) with node IDs, shape tag, score, content. Flags: `--shape daily`, `--limit 10`, `--format json`.
+Query syntax is `websearch_to_tsquery`: AND is default, `OR` explicit, `"phrases"` quoted, `-negation` drops terms. Searches genuine session history by default (skill bodies, chip prompts, and continuation summaries are excluded — they used to dominate results). Each hit shows shape/role, age, and a confidence band; weak/doc-heavy results print a coaching hint. Flags: `--shape daily`, `--limit 10`, `--include-docs` (also search documentation turns), `--format json`.
 
 **B. Recap by time** — an open-ended "catch me up". Most recent weekly + last seven daily summaries.
 ```bash

package/skill/templates/chip-spawn.md

@@ -50,15 +50,11 @@ Substitute `<own-session-id>` from your SessionStart hook output.
 **Cleanup discipline (HARD RULE):** chip prompts forbid `git clean`, `git reset --hard`, `git worktree remove`, `git checkout <other>`, raw `rm -rf` outside the worktree's tracked files.
 ````
 
-## After spawning — arm YOUR OWN watcher (HARD RULE)
+## After spawning — your watcher is already armed
 
-The chip reports back to **your** session id via `greprag send`. Nothing else reliably arms you to receive it: the SessionStart arm-directive and the turn-2 UserPromptSubmit fallback are agent-choice and may not fire, and a report that lands in an unwatched inbox sits silently until someone runs `greprag inbox` by hand. So **immediately after `spawn_task` returns, arm your own watcher** — unless you already have one running this session (one watcher covers every chip you spawn; never double-arm):
+The chip reports back to **your** session id via `greprag send`, and the detection-gated `notify` hook keeps a session-scoped watcher live for you on any unarmed turn (`adr/session-id-awareness.md`). The chip's report is filed with `to_session_id = your session`, which that watcher delivers (filter: `to_session_id = session OR NULL`). So you do **not** arm a watcher per spawn — the one auto-armed watcher covers every chip you spawn. The spawn is the whole loop.
 
-```
-Monitor (persistent:true): `while true; do greprag inbox watch --session <your-8hex> --json; echo "[restart]" >&2; sleep 1; done`
-```
-
-`<your-8hex>` = your own session id (from SessionStart). Arming is what makes the chip's "done" report surface live instead of being lost — the spawn is only half the loop.
+Safety net: if `greprag inbox watchers` shows none for your 8-hex (auto-arm disabled, or it died and the next turn hasn't re-armed yet), arm one under **Monitor (persistent:true)**: `while true; do greprag inbox watch --session <your-8hex> --json; echo "[restart]" >&2; sleep 1; done`. Never double-arm a session that already has a live watcher.
 
 ## Before composing