greprag 5.2.3 → 5.4.0

package/skill/greprag/SKILL.md

@@ -139,9 +139,9 @@ Delegating work — `spawn_task` chip vs `Agent` tool, two chip modes, the workt
 while true; do greprag inbox watch --session <own-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
 ```
 
-Run under `Monitor` with `persistent: true`. Fall back to `--project <own-project>` instead of `--session` when no session identity is available. The Stop hook only fires between user prompts; without Monitor, mid-task replies are invisible until the next stop boundary.
+Run under `Monitor` with `persistent: true`. Get `<own-session-id>` from this session's SessionStart hook system-reminder ("Your greprag session id: `<8-hex>`") — every session gets one. The `--project <own-project>` form is a legacy backstop for sessions where SessionStart never fired and should fire essentially never; using it as a default broadcasts traffic to every sibling session in the project (observed cross-talk in production). The Stop hook only fires between user prompts; without Monitor, mid-task replies are invisible until the next stop boundary.
 
-For real-time chip reports, the parent arms the same wrapped watcher (`--session <parent-session-id>` preferred, `--project <parent-project>` for multi-chip campaigns) under `Monitor` BEFORE spawning. Each stdout line = one notification. Do NOT use `Bash(run_in_background)` — it only fires on process completion, not per line; a watcher never exits, so the parent gets zero events. Do NOT use the bare `greprag inbox watch` without the `while true` wrapper — if the inner watcher dies you go silently deaf with no restart.
+For real-time chip reports, the parent arms the same wrapped watcher with `--session <parent-session-id>` (always available from the orchestrator's own SessionStart hook — substitute it before the chip prompt leaves your turn). The `--project <parent-project>` variant is for genuine multi-chip-campaign cases where you've fanned out N chips in parallel and want all reports on one stream; do not reach for it because you "forgot" your session id. Each stdout line = one notification. Do NOT use `Bash(run_in_background)` — it only fires on process completion, not per line; a watcher never exits, so the parent gets zero events. Do NOT use the bare `greprag inbox watch` without the `while true` wrapper — if the inner watcher dies you go silently deaf with no restart.
 <!-- greprag-conventions:end v3 -->
 ```
 
@@ -546,6 +546,48 @@ greprag corpus delete "<store>" --yes
 
 Episodic memory is the agent's own past. Corpus is everything else.
 
+## Step 5g — Discord DM bridge (talk to the user via Discord)
+
+When the user wants to step away from the desk and continue the conversation on their phone, route the thread through the greprag Discord bot. There are two surfaces — one-time pairing (identity) and per-session handoff (active routing).
+
+### Pairing (one-time per tenant)
+
+`greprag discord pair` generates a 6-char code. The user DMs `@greprag` on Discord with `/pair <code>`. After that, the user's snowflake is bound to their greprag tenant. DMs from that snowflake land as inbox messages on `default_project_id` (the project they paired from).
+
+You don't run this — it's a one-time setup the user does themselves. Detect "I'm paired" via `greprag discord me`: returns `paired: true` and the pairing's project_name.
+
+### Handoff (per-session routing pin)
+
+The pattern the user almost always means by "let's continue on Discord":
+
+```bash
+greprag discord handoff --ttl 60 --json
+```
+
+Run it under `Monitor` (persistent: true). The command pins DMs from the user's snowflake to (this project, this session) for 60 min, fires a confirmation DM to the user's phone, then **blocks** streaming the session's inbox to stdout as JSON. Each line that prints is one Discord DM landing — Monitor delivers them as notifications right back into your turn. The pin slides forward 30+ min on every inbound, so an active thread stays anchored.
+
+Replies go out via:
+
+```bash
+greprag send --to discord:<snowflake> "your message body"
+```
+
+The CLI handles UTF-8, Discord's 2000-char limit, optional `--ref-json '{"discord":{"reply_to_message_id":"..."}}'` for threading. **Do not use curl for this** — bash on Windows mangles em-dashes / curly quotes / emoji into Win-1252 bytes that render as `?` on Discord. Node fetch (which the CLI uses) is UTF-8 native.
+
+For long agent turns where the auto-typing's 10-second window expires, call `greprag discord typing` between work steps to refresh the indicator. Silent on success.
+
+`greprag discord unhandoff` releases the pin early (DMs revert to default project). Pin also expires naturally via the TTL.
+
+### Canonical handoff flow
+
+User says "let's keep going on Discord" / "DM me" / "I'm stepping out":
+
+1. Confirm pairing with `greprag discord me`. If unpaired, tell the user to run `greprag discord pair` and DM `/pair <code>` first.
+2. Resolve current session_id (`CLAUDE_SESSION_ID` env, or the 8-hex from SessionStart context).
+3. Arm: `Monitor` with command `greprag discord handoff --session <8-hex> --project <name> --ttl 60 --json`, persistent.
+4. Tell the user the pin is live; the bot already DMed them. Each reply from Discord will fire as a Monitor notification.
+5. On each notification, parse the JSON body (`body` field = user's message text). Draft your reply. Send via `greprag send --to discord:<snowflake> "..."`. The snowflake is in `references.discord.snowflake`.
+
 ## Step 6 — Briefing (when everything is configured)
 
 The `type` query param filters by node shape. Valid values: `turn`, `hourly`,

package/skill/templates/agent-coordination.md

@@ -59,7 +59,7 @@ All edits, tests, and commits happen in the worktree. The main checkout stays un
 **Your parent's session id is `<parent-session-id>`** — record it; you'll need it in Block 2 to address the report-back so only the parent sees it, not every sibling chip watching the same project inbox.
 ```
 
-Fill `<parent-session-id>` from your own (parent) session UUID when composing the spawn_task prompt. If you don't know your session UUID, fall back to project-level addressing throughout Block 2/3 — the chip then sends to `--to <handle>@greprag.com/<parent-project>` (project broadcast, intentional) and the parent watches `--project <parent-project>` (no `--session`). Less precise, still correct — both sides have to be project-scoped for the loop to close.
+Fill `<parent-session-id>` with the orchestrator's own session UUID before sending the prompt. The SessionStart hook prints it as the first system-reminder of every session ("Your greprag session id: `<8-hex>`") — both the full UUID and the 8-hex short form are accepted by the address grammar. Never leave the placeholder unfilled, and never substitute the literal string `<parent-session-id>` into the chip prompt. The project-level fallback (`--to <handle>@greprag.com/<parent-project>`) is a legacy backstop for sessions that predate the SessionStart hook (vanishingly rare in current sessions); cross-project broadcasts pollute every sibling chip's inbox and force the parent to demux noise. Treat that as a bug, not a default. If you genuinely cannot find your session id in the SessionStart reminder, error out rather than broadcasting at the project level. adr: `C:/greprag/adr/address-grammar.md`
 
 Path convention: `<project>/.claude/worktrees/<slug>/` — same parent directory Claude Code Desktop uses for IDE-checkbox worktrees. One place to look for any active Claude worktree. Branch prefix `chip/` distinguishes agent-spawned from IDE-spawned (`claude/<auto-name>`), so `git branch` output shows provenance at a glance. `/clean-worktrees` skill cleans both.
 
@@ -105,8 +105,8 @@ Arm a `Monitor` on your own inbox so any directive from main lands as an in-sess
 while true; do greprag inbox watch --session <own-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
 ```
 
-- `<own-session-id>` is the chip's own session UUID — same one passed as `--from-session` in Block 2. The filter narrows the stream to messages aimed at this exact session plus broadcasts; sibling chips watching the same project no longer pollute this feed.
-- If you don't have a session id (older sessions), substitute `--project <own-project>` instead of `--session <id>` — wider net but still correct.
+- `<own-session-id>` is the chip's own session UUID — find it in this session's SessionStart hook system-reminder ("Your greprag session id: `<8-hex>`"). Use the same value you passed as `--from-session` in Block 2. The session filter narrows the stream to messages aimed at this exact session plus broadcasts; sibling chips watching the same project no longer pollute this feed.
+- The `--project <own-project>` substitution exists only as a legacy backstop for sessions that predate the SessionStart hook. In current sessions the hook always fires; if the reminder isn't present, error out rather than broadcasting at the project level — project-scope makes every sibling watcher see your traffic and has been observed to cause silent cross-talk in production.
 - The chip then idles between events — no token burn, no polling. Each new inbox line = one notification.
 - Restart events go to stderr as `[wrapper] watcher exited…` — visible in the Monitor output file but not as a Monitor notification.
 - When the work is truly done and no follow-up is expected, call `TaskStop` on the Monitor task. Otherwise leave it armed until the session closes.
@@ -126,14 +126,14 @@ The chip Block 3 pattern generalizes. Any session that sends a message expecting
 If you want the chip's report the instant it lands (not on next turn), start an SSE watcher in the background BEFORE spawning the chip:
 
 ```bash
-# preferred — single chip (bash wrapper auto-restarts on inner death)
+# default — single chip, session-scoped (bash wrapper auto-restarts on inner death)
 while true; do greprag inbox watch --session <parent-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
 
-# fallback / multi-chip campaigns
-while true; do greprag inbox watch --project <parent-project>; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
+# only for genuine multi-chip campaigns (N chips fanned out in parallel, want one merged stream)
+while true; do greprag inbox watch --project <parent-project> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
 ```
 
-`--session` is the right default when the chip's Block 2 sends with `--session <parent-session-id>` — exactly one report lands in this watcher per chip. Use `--project` when you've spawned several chips at once and want all their reports on one stream (each chip still tags `--from-session <own-id>`, so the parent reads provenance per message).
+`--session` is the default. Substitute `<parent-session-id>` from the orchestrator's own SessionStart system-reminder. The `--project` form is ONLY for the case where the parent is genuinely orchestrating multiple chips in parallel and wants every chip's reports on one merged stream (each chip still tags `--from-session <own-id>` for provenance). Do not reach for `--project` because you don't have your session id handy — the SessionStart hook puts it in your context at the top of every session.
 
 **Run it under the `Monitor` agent tool.** Monitor emits one notification per stdout line — the parent agent reacts the moment a message lands. **Do NOT use `Bash(run_in_background: true)` for this** — Bash background only notifies on process completion, and a watcher runs forever, so the parent agent gets no events at all until it manually checks the output file. Burned this lesson once already.