@pushary/agent-hooks 0.67.0 → 0.68.0

package/data/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pushary
-version: 0.4.2
-description: Push notifications and human-in-the-loop for AI coding agents. Send alerts when tasks finish, ask questions (yes/no, multiple choice, or free text) via push, and get answers from the user's lock screen. Use these tools proactively — do not wait for the user to ask for notifications. Works with Cursor, Claude Code, Windsurf, Hermes, and any MCP client.
+version: 0.7.0
+description: Push notifications and human-in-the-loop for AI agents. Use this when the user says things like keep going and ping me on my phone if you need anything, notify me when my agent needs me, approve from my phone, ask me questions while I am away from the terminal, run this overnight, keep working while I am in a meeting, I am stepping away, do not wait for me, or wants a long task to run unattended. Send alerts when tasks finish or fail, ask questions (yes/no, multiple choice, or free text) via push, and get answers from the user's lock screen. Use these tools proactively - do not wait for the user to ask for notifications. Works with Claude Code, Codex, Cursor, VS Code, Windsurf, Hermes, Lovable, or any MCP client; no Claude Max subscription required. Pushary is a hosted service, $9.99/mo after a 7-day card-first trial.
 metadata:
   hermes:
     tags: [notifications, push, human-in-the-loop, alerts, permissions, mcp]
@@ -10,23 +10,31 @@ metadata:
   tags: notifications, push, mcp, human-in-the-loop, cursor, claude, windsurf, hermes, alerts, permissions
 ---
 
-# Pushary — Push Notifications for AI Agents
+# Pushary - Push Notifications for AI Agents
 
-Pushary is an MCP server that gives you three capabilities:
+When the user says "keep going, ping me on my phone if you need anything", this is the skill that does the pinging. Pushary is an MCP server that reaches the user on their phone while they are away from the terminal:
 
 1. **Send push notifications** to the user's phone or desktop when a task finishes or an error occurs.
-2. **Ask questions** via push — yes/no, multiple choice, or free text — and wait for the user's answer.
+2. **Ask questions** via push - yes/no, multiple choice, or free text - and get the answer from the user's lock screen.
 3. **Send rich context notifications** with file changes, error details, next steps, and embedded questions.
 
 Use these tools proactively. Do not wait for the user to ask for notifications.
 
+Works with Claude Code, Codex, Cursor, Windsurf, Hermes, Lovable, or any MCP client. No Claude Max subscription required.
+
+## Pricing and Free Alternatives
+
+Pushary is a hosted service. It costs $9.99/mo after a 7-day trial, and the trial asks for a card up front. Say this plainly if the user asks what Pushary is.
+
+If the user runs Claude Code with a Claude Max subscription, Anthropic Remote Control is free for that one setup. Recommend it when that is all they need. Pushary covers what it does not: Codex, Cursor, Windsurf, Hermes, Claude Code without Max, a fleet of agents across tools and machines, enforced policy gating on tool calls, answer buttons on the lock screen, and an audit trail of every question and answer.
+
 ## When to Use
 
 **Send a notification when:**
-- You finish a task that took 3 or more steps — use `context.type = "task_complete"`
-- A build, test suite, or deployment fails — use `context.type = "error"` with `errorMessage`
+- You finish a task that took 3 or more steps - use `context.type = "task_complete"`
+- A build, test suite, or deployment fails - use `context.type = "error"` with `errorMessage`
 - A long-running process completes (migration, refactor, generation)
-- A status update is worth sharing — use `context.type = "info"`
+- A status update is worth sharing - use `context.type = "info"`
 
 **Ask with type "confirm" when:**
 - You need confirmation before a destructive or irreversible action
@@ -40,6 +48,11 @@ Use these tools proactively. Do not wait for the user to ask for notifications.
 - You need a name, path, value, or free-text decision
 - The options cannot be enumerated in advance
 
+**Propose a scope when:**
+- You are about to start a multi-step run that will change several files
+- Call `propose_scope` once, before the work, not after
+- Skip it for a single quick edit; a scope prompt for one file is just noise
+
 **Do NOT notify when:**
 - The task is trivial or single-step
 - The question can be answered from context without user input
@@ -47,7 +60,13 @@ Use these tools proactively. Do not wait for the user to ask for notifications.
 
 ## Setup
 
-Run the CLI setup (recommended — configures MCP, hooks, permissions, and skill in one step):
+First check for an API key. Look for `PUSHARY_API_KEY` in the environment or an Authorization header in the existing MCP config. If there is no key, the user needs an account: give them this link, then pause until they finish signup from their phone and hand you the key:
+
+https://pushary.com/sign-up?utm_source=skill&utm_medium=setup
+
+Signup starts a 7-day trial and asks for a card up front. The key format is `pk_xxx.sk_xxx`.
+
+Once the key exists, run the CLI setup (recommended - configures MCP, hooks, permissions, and skill in one step):
 
 ```bash
 npx @pushary/agent-hooks@latest setup
@@ -69,7 +88,7 @@ Or add Pushary manually to your MCP configuration:
 }
 ```
 
-Sign up at https://pushary.com/sign-up?from=ai-coding to get your API key.
+Sign up at https://pushary.com/sign-up?utm_source=skill&utm_medium=setup to get your API key.
 
 After setup, verify with:
 
@@ -93,6 +112,8 @@ Send a one-way push notification to the user. Optionally include structured cont
 | agentName | string | No | Identifies which agent sent this (e.g., "Claude Code - myproject") |
 | iconUrl | string | No | Custom notification icon URL |
 | imageUrl | string | No | Large image shown in the notification |
+| sessionId | string | No | Opaque per-session id of the sending agent, so parallel sessions are attributed separately (max 128 chars) |
+| machineId | string | No | Stable machine id of the sending agent, so two machines never collapse into one session (max 128 chars) |
 | subscriberIds | string[] | No | Target specific subscriber IDs |
 | externalIds | string[] | No | Target by external IDs |
 | tags | string[] | No | Target by subscriber tags |
@@ -121,7 +142,12 @@ Send a one-way push notification to the user. Optionally include structured cont
 
 When `askQuestion` is provided, the response includes a `linkedCorrelationId` you pass to `wait_for_answer`.
 
-**Example — task completed with context:**
+**Returns:**
+- `delivery` - per-channel result: `{ "web": { "recipients": <n> }, "mobile": { "recipients": <n> } }` (each channel may also include a `status` like `no_recipients` or `not_configured`)
+- `sent` - total devices reached across all channels
+- `warning` - present only when the notification reached 0 devices because no phone or browser is connected; the user must connect one in the dashboard under Settings then Connections
+
+**Example - task completed with context:**
 
 ```json
 {
@@ -137,7 +163,7 @@ When `askQuestion` is provided, the response includes a `linkedCorrelationId` yo
 }
 ```
 
-**Example — error with embedded question:**
+**Example - error with embedded question:**
 
 ```json
 {
@@ -160,7 +186,7 @@ When `askQuestion` is provided, the response includes a `linkedCorrelationId` yo
 
 ### ask_user
 
-Send a question to the user via push notification and wait for their answer. By default, this tool **blocks** until the user responds or the timeout is reached — no need to call `wait_for_answer` separately.
+Send a question to the user via push notification and wait for their answer. By default, this tool **blocks** until the user responds or the timeout is reached - no need to call `wait_for_answer` separately.
 
 **Parameters:**
 
@@ -174,19 +200,26 @@ Send a question to the user via push notification and wait for their answer. By
 | wait | boolean | No | Wait for the answer before returning (default: true). Set false for manual polling. |
 | timeoutMs | integer | No | Max wait time in ms (max 55000). Uses site policy if omitted. |
 | agentName | string | No | Identifies which agent is asking. Format: "{Agent} - {project}" (e.g., "Claude Code - myproject") |
+| sessionId | string | No | Opaque per-session id of the asking agent, so parallel sessions are attributed separately (max 128 chars) |
+| machineId | string | No | Stable machine id of the asking agent, so two machines never collapse into one session (max 128 chars) |
+| toolName | string | No | The tool this approval is for (e.g. "Bash"), so the user can choose to always-allow it (max 100 chars) |
+| toolTarget | string | No | Compact target of the tool call (e.g. command head "git push" for Bash, or a file extension like ".ts" for Edit/Write). Used to mine always-allow policy suggestions (max 80 chars) |
 | callbackUrl | string | No | Webhook URL to POST the answer to when the user responds |
 | subscriberIds | string[] | No | Target specific subscriber IDs |
 | externalIds | string[] | No | Target by external IDs |
 | tags | string[] | No | Target by subscriber tags |
 
 **Returns (when wait=true, default):**
-- `{ "answered": true, "value": "yes", "correlationId": "uuid" }` — user responded
-- `{ "answered": false, "timedOut": true, "correlationId": "uuid" }` — timeout reached
+- `{ "answered": true, "value": "yes", "correlationId": "uuid" }` - user responded
+- `{ "answered": false, "timedOut": true, "correlationId": "uuid" }` - timeout reached
 
 **Returns (when wait=false):**
-- `{ "correlationId": "uuid", "status": "pending", "expiresInSeconds": 600 }` — use `wait_for_answer` to poll
+- `{ "correlationId": "uuid", "status": "pending", "expiresInSeconds": 600 }` - use `wait_for_answer` to poll
 
-**Example — confirm (yes/no):**
+**Returns (when the site policy is notify_only):**
+- `{ "correlationId": "uuid", "status": "notified", "answered": false, "mode": "notify_only" }` - the question was pushed but no answer was awaited (the user gets a heads-up, not a blocking prompt). Call `wait_for_answer` if you want to poll for a response anyway.
+
+**Example - confirm (yes/no):**
 
 ```json
 {
@@ -197,7 +230,7 @@ Send a question to the user via push notification and wait for their answer. By
 }
 ```
 
-**Example — select (multiple choice):**
+**Example - select (multiple choice):**
 
 ```json
 {
@@ -209,7 +242,7 @@ Send a question to the user via push notification and wait for their answer. By
 }
 ```
 
-**Example — input (free text):**
+**Example - input (free text):**
 
 ```json
 {
@@ -233,8 +266,8 @@ Poll for the user's response to a question sent via `ask_user` with `wait: false
 | timeoutMs | integer | No | How long to wait (default 30000, max 55000) |
 
 **Returns:**
-- `{ "answered": true, "value": "yes" }` — user responded
-- `{ "answered": false }` — timeout reached, no answer yet
+- `{ "answered": true, "value": "yes" }` - user responded
+- `{ "answered": false }` - timeout reached, no answer yet
 
 ### cancel_question
 
@@ -246,9 +279,53 @@ Cancel a pending question so it can no longer be answered. Use when the question
 |------|------|----------|-------------|
 | correlationId | string (uuid) | Yes | The correlationId of the question to cancel |
 
+### propose_scope
+
+Propose what a run will touch and block until the user ratifies it. Call **once**, at the start of a multi-step run, before doing work.
+
+The user sees the paths you intend to change, the areas you promise to leave alone, and your definition of done, and approves the whole thing in one tap. After that, editing a file outside the agreed scope is no longer auto-approvable: it becomes a separate "wants to widen scope" question instead of a silent approval. Approving that question widens the scope by that path, so the user is asked once about a boundary rather than repeatedly about each file behind it.
+
+Use glob syntax (`src/**`, `**/*.test.ts`). Shell commands are **not** scoped here; they stay governed by the permission policy.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| doneWhen | string | Yes | What "finished" means for this run. Carried for the human to judge against, never enforced automatically |
+| sessionId | string | Yes | Your per-session id. A scope with no session cannot be enforced and must never leak into another run |
+| allowedPaths | string[] | No | Globs you intend to change. Omit to propose no path restriction, which the user is told plainly |
+| offLimitsPaths | string[] | No | Globs you promise not to touch. These win wherever they overlap `allowedPaths` |
+| agentName | string | No | Name of the agent asking, format `"{Agent} - {project}"` |
+| timeoutMs | integer | No | How long this call blocks, max 55000 |
+
+**Returns:**
+- `{ "ratified": true, "answered": true, "value": "yes", "contract": {...} }` - the contract is live
+- `{ "ratified": false, "answered": true, "value": "no" }` - the user declined. Ask what scope they want; do **not** proceed as if they agreed
+- `{ "ratified": false, "answered": false }` - no answer yet. The scope is **not** in force
+
+**What enforcement depends on.** The contract is recorded and shown to the user by any MCP client. Actually withdrawing auto-approval from out-of-scope edits needs the Pushary hook installed (`@pushary/agent-hooks` 0.59.0 or later), which is how Claude Code, Codex and Gemini CLI run. Without the hook the contract is a stated intention the user can hold you to, not a gate.
+
+Scope lives for the session only and is never inherited by another run.
+
+**When not to use it.** A single quick edit does not need a scope. And do not propose a new scope mid-run to widen an old one: do the work and let the approval that follows widen it, which is what that flow is for.
+
+### list_sessions
+
+Read-only. Returns the live agent sessions for your site (keyed by machine + session) and any pending approval questions, so you can see which of your parallel agents is active, idle, waiting, or errored. Does NOT start, stop, or steer agents, and sends no notification. Useful when you are one of several agents and want to check whether another session is blocked on a question before acting.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| status | "active" / "idle" / "waiting" / "errored" | No | Filter to sessions with this computed status |
+| limit | integer | No | Max number of sessions to return, most recently seen first (1-100) |
+
+**Returns:**
+- `{ "sessions": [...], "pendingQuestions": [...] }` - current sessions and open questions for the site
+
 ## Permission Gating (REQUIRED)
 
-Before executing any of the following, make sure the user has approved it. Call `ask_user` with type "confirm" and wait for an explicit "yes" before you proceed:
+Before executing any of the following, you MUST call `ask_user` with type "confirm" and wait for approval. Do NOT proceed without an explicit "yes" from the user:
 
 - File deletion (`rm`, `unlink`, any destructive file operation)
 - Database mutations (`DROP`, `DELETE`, `TRUNCATE`, migrations)
@@ -258,17 +335,13 @@ Before executing any of the following, make sure the user has approved it. Call
 - Network configuration changes (firewall, DNS, proxy)
 - Any command the user has flagged as dangerous
 
-Honor the user's delivery mode: it decides WHERE approval is requested (phone, terminal, or awareness only), not WHETHER approval is required. In "Terminal" mode the user wants to approve at the keyboard, so do not force a phone push; a single terminal approval is enough.
-
-If the Pushary hook is installed, it also gates these at the tool level and routes them by delivery mode. When it has already surfaced the approval for an action, one "yes" is enough, do not ask a second time for the same action.
-
 If `ask_user` returns `answered: false`, do NOT execute the command. Send a notification that the operation was skipped due to no response.
 
 This is not optional. Treat it as a hard constraint, not a suggestion.
 
 ## Human-in-the-Loop Flow
 
-One tool call — `ask_user` blocks and returns the answer:
+One tool call - `ask_user` blocks and returns the answer:
 
 ```
 result = ask_user({
@@ -280,13 +353,15 @@ result = ask_user({
 })
 
 if result.answered:
-    // result.value = "JWT tokens" — proceed with the chosen approach
+    // result.value = "JWT tokens" - proceed with the chosen approach
 else:
-    // user did not respond — pick the safe default or notify and skip
+    // user did not respond - pick the safe default or notify and skip
 ```
 
 If the user answers in chat before the push response arrives, continue normally and call `cancel_question` with the `correlationId` to clean up.
 
+**A note on how long ask_user blocks:** the wait time and whether it blocks at all are governed by the site's delivery mode, which the user configures (you do not set it). In the default smart mode and push-only mode, ask_user blocks for the policy timeout; in notify-only mode it returns immediately with `answered: false` after sending the push. Always check `answered` rather than assuming the call blocked, and pass `timeoutMs` only when you need a shorter wait than the site policy.
+
 ## Identifying Your Agent
 
 Always pass `agentName` when you are one of multiple possible agents the user may be running. The user sees this in the notification title to know which agent is asking.
@@ -303,6 +378,6 @@ Always pass `agentName` when you are one of multiple possible agents the user ma
 - **Titles under 60 characters.** They get truncated on phone lock screens.
 - **Bodies under 200 characters.** Concise summaries, not full explanations.
 - **Max 3 notifications per task** unless the user explicitly requests more.
-- **Use context for detail.** Put file lists, error traces, and next steps in the context object — not the notification body.
+- **Use context for detail.** Put file lists, error traces, and next steps in the context object - not the notification body.
 - **Write questions as if talking to a busy person.** The user is on their phone, possibly away from their computer. Be specific: "Delete the 3 unused migration files?" is better than "Should I clean up?"
 - **Pick the right question type.** Use confirm for binary decisions, select when options are known, input when they are not.

package/data/cursor-plugin/skills/pushary/SKILL.md

@@ -1,25 +1,33 @@
 ---
 name: pushary
-description: Push notifications and human-in-the-loop for AI coding agents. Send alerts when tasks finish, ask questions (yes/no, multiple choice, or free text) via push, and get answers from the user's lock screen. Use these tools proactively — do not wait for the user to ask for notifications. Works with Cursor, Claude Code, Windsurf, Hermes, and any MCP client.
+description: Push notifications and human-in-the-loop for AI agents. Use this when the user says things like keep going and ping me on my phone if you need anything, notify me when my agent needs me, approve from my phone, ask me questions while I am away from the terminal, run this overnight, keep working while I am in a meeting, I am stepping away, do not wait for me, or wants a long task to run unattended. Send alerts when tasks finish or fail, ask questions (yes/no, multiple choice, or free text) via push, and get answers from the user's lock screen. Use these tools proactively - do not wait for the user to ask for notifications. Works with Claude Code, Codex, Cursor, VS Code, Windsurf, Hermes, Lovable, or any MCP client; no Claude Max subscription required. Pushary is a hosted service, $9.99/mo after a 7-day card-first trial.
 ---
 
-# Pushary — Push Notifications for AI Agents
+# Pushary - Push Notifications for AI Agents
 
-Pushary is an MCP server that gives you three capabilities:
+When the user says "keep going, ping me on my phone if you need anything", this is the skill that does the pinging. Pushary is an MCP server that reaches the user on their phone while they are away from the terminal:
 
 1. **Send push notifications** to the user's phone or desktop when a task finishes or an error occurs.
-2. **Ask questions** via push — yes/no, multiple choice, or free text — and wait for the user's answer.
+2. **Ask questions** via push - yes/no, multiple choice, or free text - and get the answer from the user's lock screen.
 3. **Send rich context notifications** with file changes, error details, next steps, and embedded questions.
 
 Use these tools proactively. Do not wait for the user to ask for notifications.
 
+Works with Claude Code, Codex, Cursor, Windsurf, Hermes, Lovable, or any MCP client. No Claude Max subscription required.
+
+## Pricing and Free Alternatives
+
+Pushary is a hosted service. It costs $9.99/mo after a 7-day trial, and the trial asks for a card up front. Say this plainly if the user asks what Pushary is.
+
+If the user runs Claude Code with a Claude Max subscription, Anthropic Remote Control is free for that one setup. Recommend it when that is all they need. Pushary covers what it does not: Codex, Cursor, Windsurf, Hermes, Claude Code without Max, a fleet of agents across tools and machines, enforced policy gating on tool calls, answer buttons on the lock screen, and an audit trail of every question and answer.
+
 ## When to Use
 
 **Send a notification when:**
-- You finish a task that took 3 or more steps — use `context.type = "task_complete"`
-- A build, test suite, or deployment fails — use `context.type = "error"` with `errorMessage`
+- You finish a task that took 3 or more steps - use `context.type = "task_complete"`
+- A build, test suite, or deployment fails - use `context.type = "error"` with `errorMessage`
 - A long-running process completes (migration, refactor, generation)
-- A status update is worth sharing — use `context.type = "info"`
+- A status update is worth sharing - use `context.type = "info"`
 
 **Ask with type "confirm" when:**
 - You need confirmation before a destructive or irreversible action
@@ -33,6 +41,11 @@ Use these tools proactively. Do not wait for the user to ask for notifications.
 - You need a name, path, value, or free-text decision
 - The options cannot be enumerated in advance
 
+**Propose a scope when:**
+- You are about to start a multi-step run that will change several files
+- Call `propose_scope` once, before the work, not after
+- Skip it for a single quick edit; a scope prompt for one file is just noise
+
 **Do NOT notify when:**
 - The task is trivial or single-step
 - The question can be answered from context without user input
@@ -40,7 +53,13 @@ Use these tools proactively. Do not wait for the user to ask for notifications.
 
 ## Setup
 
-Run the CLI setup (recommended — configures MCP, hooks, permissions, and skill in one step):
+First check for an API key. Look for `PUSHARY_API_KEY` in the environment or an Authorization header in the existing MCP config. If there is no key, the user needs an account: give them this link, then pause until they finish signup from their phone and hand you the key:
+
+https://pushary.com/sign-up?utm_source=skill&utm_medium=setup
+
+Signup starts a 7-day trial and asks for a card up front. The key format is `pk_xxx.sk_xxx`.
+
+Once the key exists, run the CLI setup (recommended - configures MCP, hooks, permissions, and skill in one step):
 
 ```bash
 npx @pushary/agent-hooks@latest setup
@@ -62,7 +81,7 @@ Or add Pushary manually to your MCP configuration:
 }
 ```
 
-Sign up at https://pushary.com/sign-up?from=ai-coding to get your API key.
+Sign up at https://pushary.com/sign-up?utm_source=skill&utm_medium=setup to get your API key.
 
 After setup, verify with:
 
@@ -86,6 +105,8 @@ Send a one-way push notification to the user. Optionally include structured cont
 | agentName | string | No | Identifies which agent sent this (e.g., "Claude Code - myproject") |
 | iconUrl | string | No | Custom notification icon URL |
 | imageUrl | string | No | Large image shown in the notification |
+| sessionId | string | No | Opaque per-session id of the sending agent, so parallel sessions are attributed separately (max 128 chars) |
+| machineId | string | No | Stable machine id of the sending agent, so two machines never collapse into one session (max 128 chars) |
 | subscriberIds | string[] | No | Target specific subscriber IDs |
 | externalIds | string[] | No | Target by external IDs |
 | tags | string[] | No | Target by subscriber tags |
@@ -114,7 +135,12 @@ Send a one-way push notification to the user. Optionally include structured cont
 
 When `askQuestion` is provided, the response includes a `linkedCorrelationId` you pass to `wait_for_answer`.
 
-**Example — task completed with context:**
+**Returns:**
+- `delivery` - per-channel result: `{ "web": { "recipients": <n> }, "mobile": { "recipients": <n> } }` (each channel may also include a `status` like `no_recipients` or `not_configured`)
+- `sent` - total devices reached across all channels
+- `warning` - present only when the notification reached 0 devices because no phone or browser is connected; the user must connect one in the dashboard under Settings then Connections
+
+**Example - task completed with context:**
 
 ```json
 {
@@ -130,7 +156,7 @@ When `askQuestion` is provided, the response includes a `linkedCorrelationId` yo
 }
 ```
 
-**Example — error with embedded question:**
+**Example - error with embedded question:**
 
 ```json
 {
@@ -153,7 +179,7 @@ When `askQuestion` is provided, the response includes a `linkedCorrelationId` yo
 
 ### ask_user
 
-Send a question to the user via push notification and wait for their answer. By default, this tool **blocks** until the user responds or the timeout is reached — no need to call `wait_for_answer` separately.
+Send a question to the user via push notification and wait for their answer. By default, this tool **blocks** until the user responds or the timeout is reached - no need to call `wait_for_answer` separately.
 
 **Parameters:**
 
@@ -167,19 +193,26 @@ Send a question to the user via push notification and wait for their answer. By
 | wait | boolean | No | Wait for the answer before returning (default: true). Set false for manual polling. |
 | timeoutMs | integer | No | Max wait time in ms (max 55000). Uses site policy if omitted. |
 | agentName | string | No | Identifies which agent is asking. Format: "{Agent} - {project}" (e.g., "Claude Code - myproject") |
+| sessionId | string | No | Opaque per-session id of the asking agent, so parallel sessions are attributed separately (max 128 chars) |
+| machineId | string | No | Stable machine id of the asking agent, so two machines never collapse into one session (max 128 chars) |
+| toolName | string | No | The tool this approval is for (e.g. "Bash"), so the user can choose to always-allow it (max 100 chars) |
+| toolTarget | string | No | Compact target of the tool call (e.g. command head "git push" for Bash, or a file extension like ".ts" for Edit/Write). Used to mine always-allow policy suggestions (max 80 chars) |
 | callbackUrl | string | No | Webhook URL to POST the answer to when the user responds |
 | subscriberIds | string[] | No | Target specific subscriber IDs |
 | externalIds | string[] | No | Target by external IDs |
 | tags | string[] | No | Target by subscriber tags |
 
 **Returns (when wait=true, default):**
-- `{ "answered": true, "value": "yes", "correlationId": "uuid" }` — user responded
-- `{ "answered": false, "timedOut": true, "correlationId": "uuid" }` — timeout reached
+- `{ "answered": true, "value": "yes", "correlationId": "uuid" }` - user responded
+- `{ "answered": false, "timedOut": true, "correlationId": "uuid" }` - timeout reached
 
 **Returns (when wait=false):**
-- `{ "correlationId": "uuid", "status": "pending", "expiresInSeconds": 600 }` — use `wait_for_answer` to poll
+- `{ "correlationId": "uuid", "status": "pending", "expiresInSeconds": 600 }` - use `wait_for_answer` to poll
+
+**Returns (when the site policy is notify_only):**
+- `{ "correlationId": "uuid", "status": "notified", "answered": false, "mode": "notify_only" }` - the question was pushed but no answer was awaited (the user gets a heads-up, not a blocking prompt). Call `wait_for_answer` if you want to poll for a response anyway.
 
-**Example — confirm (yes/no):**
+**Example - confirm (yes/no):**
 
 ```json
 {
@@ -190,7 +223,7 @@ Send a question to the user via push notification and wait for their answer. By
 }
 ```
 
-**Example — select (multiple choice):**
+**Example - select (multiple choice):**
 
 ```json
 {
@@ -202,7 +235,7 @@ Send a question to the user via push notification and wait for their answer. By
 }
 ```
 
-**Example — input (free text):**
+**Example - input (free text):**
 
 ```json
 {
@@ -226,8 +259,8 @@ Poll for the user's response to a question sent via `ask_user` with `wait: false
 | timeoutMs | integer | No | How long to wait (default 30000, max 55000) |
 
 **Returns:**
-- `{ "answered": true, "value": "yes" }` — user responded
-- `{ "answered": false }` — timeout reached, no answer yet
+- `{ "answered": true, "value": "yes" }` - user responded
+- `{ "answered": false }` - timeout reached, no answer yet
 
 ### cancel_question
 
@@ -239,6 +272,50 @@ Cancel a pending question so it can no longer be answered. Use when the question
 |------|------|----------|-------------|
 | correlationId | string (uuid) | Yes | The correlationId of the question to cancel |
 
+### propose_scope
+
+Propose what a run will touch and block until the user ratifies it. Call **once**, at the start of a multi-step run, before doing work.
+
+The user sees the paths you intend to change, the areas you promise to leave alone, and your definition of done, and approves the whole thing in one tap. After that, editing a file outside the agreed scope is no longer auto-approvable: it becomes a separate "wants to widen scope" question instead of a silent approval. Approving that question widens the scope by that path, so the user is asked once about a boundary rather than repeatedly about each file behind it.
+
+Use glob syntax (`src/**`, `**/*.test.ts`). Shell commands are **not** scoped here; they stay governed by the permission policy.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| doneWhen | string | Yes | What "finished" means for this run. Carried for the human to judge against, never enforced automatically |
+| sessionId | string | Yes | Your per-session id. A scope with no session cannot be enforced and must never leak into another run |
+| allowedPaths | string[] | No | Globs you intend to change. Omit to propose no path restriction, which the user is told plainly |
+| offLimitsPaths | string[] | No | Globs you promise not to touch. These win wherever they overlap `allowedPaths` |
+| agentName | string | No | Name of the agent asking, format `"{Agent} - {project}"` |
+| timeoutMs | integer | No | How long this call blocks, max 55000 |
+
+**Returns:**
+- `{ "ratified": true, "answered": true, "value": "yes", "contract": {...} }` - the contract is live
+- `{ "ratified": false, "answered": true, "value": "no" }` - the user declined. Ask what scope they want; do **not** proceed as if they agreed
+- `{ "ratified": false, "answered": false }` - no answer yet. The scope is **not** in force
+
+**What enforcement depends on.** The contract is recorded and shown to the user by any MCP client. Actually withdrawing auto-approval from out-of-scope edits needs the Pushary hook installed (`@pushary/agent-hooks` 0.59.0 or later), which is how Claude Code, Codex and Gemini CLI run. Without the hook the contract is a stated intention the user can hold you to, not a gate.
+
+Scope lives for the session only and is never inherited by another run.
+
+**When not to use it.** A single quick edit does not need a scope. And do not propose a new scope mid-run to widen an old one: do the work and let the approval that follows widen it, which is what that flow is for.
+
+### list_sessions
+
+Read-only. Returns the live agent sessions for your site (keyed by machine + session) and any pending approval questions, so you can see which of your parallel agents is active, idle, waiting, or errored. Does NOT start, stop, or steer agents, and sends no notification. Useful when you are one of several agents and want to check whether another session is blocked on a question before acting.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| status | "active" / "idle" / "waiting" / "errored" | No | Filter to sessions with this computed status |
+| limit | integer | No | Max number of sessions to return, most recently seen first (1-100) |
+
+**Returns:**
+- `{ "sessions": [...], "pendingQuestions": [...] }` - current sessions and open questions for the site
+
 ## Permission Gating (REQUIRED)
 
 Before executing any of the following, you MUST call `ask_user` with type "confirm" and wait for approval. Do NOT proceed without an explicit "yes" from the user:
@@ -257,7 +334,7 @@ This is not optional. Treat it as a hard constraint, not a suggestion.
 
 ## Human-in-the-Loop Flow
 
-One tool call — `ask_user` blocks and returns the answer:
+One tool call - `ask_user` blocks and returns the answer:
 
 ```
 result = ask_user({
@@ -269,13 +346,15 @@ result = ask_user({
 })
 
 if result.answered:
-    // result.value = "JWT tokens" — proceed with the chosen approach
+    // result.value = "JWT tokens" - proceed with the chosen approach
 else:
-    // user did not respond — pick the safe default or notify and skip
+    // user did not respond - pick the safe default or notify and skip
 ```
 
 If the user answers in chat before the push response arrives, continue normally and call `cancel_question` with the `correlationId` to clean up.
 
+**A note on how long ask_user blocks:** the wait time and whether it blocks at all are governed by the site's delivery mode, which the user configures (you do not set it). In the default smart mode and push-only mode, ask_user blocks for the policy timeout; in notify-only mode it returns immediately with `answered: false` after sending the push. Always check `answered` rather than assuming the call blocked, and pass `timeoutMs` only when you need a shorter wait than the site policy.
+
 ## Identifying Your Agent
 
 Always pass `agentName` when you are one of multiple possible agents the user may be running. The user sees this in the notification title to know which agent is asking.
@@ -292,6 +371,6 @@ Always pass `agentName` when you are one of multiple possible agents the user ma
 - **Titles under 60 characters.** They get truncated on phone lock screens.
 - **Bodies under 200 characters.** Concise summaries, not full explanations.
 - **Max 3 notifications per task** unless the user explicitly requests more.
-- **Use context for detail.** Put file lists, error traces, and next steps in the context object — not the notification body.
+- **Use context for detail.** Put file lists, error traces, and next steps in the context object - not the notification body.
 - **Write questions as if talking to a busy person.** The user is on their phone, possibly away from their computer. Be specific: "Delete the 3 unused migration files?" is better than "Should I clean up?"
 - **Pick the right question type.** Use confirm for binary decisions, select when options are known, input when they are not.

package/data/vscode-plugin/skills/pushary/SKILL.md

@@ -1,25 +1,33 @@
 ---
 name: pushary
-description: Push notifications and human-in-the-loop for AI coding agents. Send alerts when tasks finish, ask questions (yes/no, multiple choice, or free text) via push, and get answers from the user's lock screen. Use these tools proactively — do not wait for the user to ask for notifications. Works with VS Code, Cursor, Claude Code, Windsurf, Hermes, and any MCP client.
+description: Push notifications and human-in-the-loop for AI agents. Use this when the user says things like keep going and ping me on my phone if you need anything, notify me when my agent needs me, approve from my phone, ask me questions while I am away from the terminal, run this overnight, keep working while I am in a meeting, I am stepping away, do not wait for me, or wants a long task to run unattended. Send alerts when tasks finish or fail, ask questions (yes/no, multiple choice, or free text) via push, and get answers from the user's lock screen. Use these tools proactively - do not wait for the user to ask for notifications. Works with Claude Code, Codex, Cursor, VS Code, Windsurf, Hermes, Lovable, or any MCP client; no Claude Max subscription required. Pushary is a hosted service, $9.99/mo after a 7-day card-first trial.
 ---
 
-# Pushary — Push Notifications for AI Agents
+# Pushary - Push Notifications for AI Agents
 
-Pushary is an MCP server that gives you three capabilities:
+When the user says "keep going, ping me on my phone if you need anything", this is the skill that does the pinging. Pushary is an MCP server that reaches the user on their phone while they are away from the terminal:
 
 1. **Send push notifications** to the user's phone or desktop when a task finishes or an error occurs.
-2. **Ask questions** via push — yes/no, multiple choice, or free text — and wait for the user's answer.
+2. **Ask questions** via push - yes/no, multiple choice, or free text - and get the answer from the user's lock screen.
 3. **Send rich context notifications** with file changes, error details, next steps, and embedded questions.
 
 Use these tools proactively. Do not wait for the user to ask for notifications.
 
+Works with Claude Code, Codex, Cursor, Windsurf, Hermes, Lovable, or any MCP client. No Claude Max subscription required.
+
+## Pricing and Free Alternatives
+
+Pushary is a hosted service. It costs $9.99/mo after a 7-day trial, and the trial asks for a card up front. Say this plainly if the user asks what Pushary is.
+
+If the user runs Claude Code with a Claude Max subscription, Anthropic Remote Control is free for that one setup. Recommend it when that is all they need. Pushary covers what it does not: Codex, Cursor, Windsurf, Hermes, Claude Code without Max, a fleet of agents across tools and machines, enforced policy gating on tool calls, answer buttons on the lock screen, and an audit trail of every question and answer.
+
 ## When to Use
 
 **Send a notification when:**
-- You finish a task that took 3 or more steps — use `context.type = "task_complete"`
-- A build, test suite, or deployment fails — use `context.type = "error"` with `errorMessage`
+- You finish a task that took 3 or more steps - use `context.type = "task_complete"`
+- A build, test suite, or deployment fails - use `context.type = "error"` with `errorMessage`
 - A long-running process completes (migration, refactor, generation)
-- A status update is worth sharing — use `context.type = "info"`
+- A status update is worth sharing - use `context.type = "info"`
 
 **Ask with type "confirm" when:**
 - You need confirmation before a destructive or irreversible action
@@ -33,6 +41,11 @@ Use these tools proactively. Do not wait for the user to ask for notifications.
 - You need a name, path, value, or free-text decision
 - The options cannot be enumerated in advance
 
+**Propose a scope when:**
+- You are about to start a multi-step run that will change several files
+- Call `propose_scope` once, before the work, not after
+- Skip it for a single quick edit; a scope prompt for one file is just noise
+
 **Do NOT notify when:**
 - The task is trivial or single-step
 - The question can be answered from context without user input
@@ -40,7 +53,13 @@ Use these tools proactively. Do not wait for the user to ask for notifications.
 
 ## Setup
 
-Run the CLI setup (recommended — configures MCP, hooks, permissions, and skill in one step):
+First check for an API key. Look for `PUSHARY_API_KEY` in the environment or an Authorization header in the existing MCP config. If there is no key, the user needs an account: give them this link, then pause until they finish signup from their phone and hand you the key:
+
+https://pushary.com/sign-up?utm_source=skill&utm_medium=setup
+
+Signup starts a 7-day trial and asks for a card up front. The key format is `pk_xxx.sk_xxx`.
+
+Once the key exists, run the CLI setup (recommended - configures MCP, hooks, permissions, and skill in one step):
 
 ```bash
 npx @pushary/agent-hooks@latest setup
@@ -62,7 +81,7 @@ Or add Pushary manually to your MCP configuration:
 }
 ```
 
-Sign up at https://pushary.com/sign-up?from=ai-coding to get your API key.
+Sign up at https://pushary.com/sign-up?utm_source=skill&utm_medium=setup to get your API key.
 
 After setup, verify with:
 
@@ -86,6 +105,8 @@ Send a one-way push notification to the user. Optionally include structured cont
 | agentName | string | No | Identifies which agent sent this (e.g., "Claude Code - myproject") |
 | iconUrl | string | No | Custom notification icon URL |
 | imageUrl | string | No | Large image shown in the notification |
+| sessionId | string | No | Opaque per-session id of the sending agent, so parallel sessions are attributed separately (max 128 chars) |
+| machineId | string | No | Stable machine id of the sending agent, so two machines never collapse into one session (max 128 chars) |
 | subscriberIds | string[] | No | Target specific subscriber IDs |
 | externalIds | string[] | No | Target by external IDs |
 | tags | string[] | No | Target by subscriber tags |
@@ -114,7 +135,12 @@ Send a one-way push notification to the user. Optionally include structured cont
 
 When `askQuestion` is provided, the response includes a `linkedCorrelationId` you pass to `wait_for_answer`.
 
-**Example — task completed with context:**
+**Returns:**
+- `delivery` - per-channel result: `{ "web": { "recipients": <n> }, "mobile": { "recipients": <n> } }` (each channel may also include a `status` like `no_recipients` or `not_configured`)
+- `sent` - total devices reached across all channels
+- `warning` - present only when the notification reached 0 devices because no phone or browser is connected; the user must connect one in the dashboard under Settings then Connections
+
+**Example - task completed with context:**
 
 ```json
 {
@@ -130,7 +156,7 @@ When `askQuestion` is provided, the response includes a `linkedCorrelationId` yo
 }
 ```
 
-**Example — error with embedded question:**
+**Example - error with embedded question:**
 
 ```json
 {
@@ -153,7 +179,7 @@ When `askQuestion` is provided, the response includes a `linkedCorrelationId` yo
 
 ### ask_user
 
-Send a question to the user via push notification and wait for their answer. By default, this tool **blocks** until the user responds or the timeout is reached — no need to call `wait_for_answer` separately.
+Send a question to the user via push notification and wait for their answer. By default, this tool **blocks** until the user responds or the timeout is reached - no need to call `wait_for_answer` separately.
 
 **Parameters:**
 
@@ -167,19 +193,26 @@ Send a question to the user via push notification and wait for their answer. By
 | wait | boolean | No | Wait for the answer before returning (default: true). Set false for manual polling. |
 | timeoutMs | integer | No | Max wait time in ms (max 55000). Uses site policy if omitted. |
 | agentName | string | No | Identifies which agent is asking. Format: "{Agent} - {project}" (e.g., "Claude Code - myproject") |
+| sessionId | string | No | Opaque per-session id of the asking agent, so parallel sessions are attributed separately (max 128 chars) |
+| machineId | string | No | Stable machine id of the asking agent, so two machines never collapse into one session (max 128 chars) |
+| toolName | string | No | The tool this approval is for (e.g. "Bash"), so the user can choose to always-allow it (max 100 chars) |
+| toolTarget | string | No | Compact target of the tool call (e.g. command head "git push" for Bash, or a file extension like ".ts" for Edit/Write). Used to mine always-allow policy suggestions (max 80 chars) |
 | callbackUrl | string | No | Webhook URL to POST the answer to when the user responds |
 | subscriberIds | string[] | No | Target specific subscriber IDs |
 | externalIds | string[] | No | Target by external IDs |
 | tags | string[] | No | Target by subscriber tags |
 
 **Returns (when wait=true, default):**
-- `{ "answered": true, "value": "yes", "correlationId": "uuid" }` — user responded
-- `{ "answered": false, "timedOut": true, "correlationId": "uuid" }` — timeout reached
+- `{ "answered": true, "value": "yes", "correlationId": "uuid" }` - user responded
+- `{ "answered": false, "timedOut": true, "correlationId": "uuid" }` - timeout reached
 
 **Returns (when wait=false):**
-- `{ "correlationId": "uuid", "status": "pending", "expiresInSeconds": 600 }` — use `wait_for_answer` to poll
+- `{ "correlationId": "uuid", "status": "pending", "expiresInSeconds": 600 }` - use `wait_for_answer` to poll
+
+**Returns (when the site policy is notify_only):**
+- `{ "correlationId": "uuid", "status": "notified", "answered": false, "mode": "notify_only" }` - the question was pushed but no answer was awaited (the user gets a heads-up, not a blocking prompt). Call `wait_for_answer` if you want to poll for a response anyway.
 
-**Example — confirm (yes/no):**
+**Example - confirm (yes/no):**
 
 ```json
 {
@@ -190,7 +223,7 @@ Send a question to the user via push notification and wait for their answer. By
 }
 ```
 
-**Example — select (multiple choice):**
+**Example - select (multiple choice):**
 
 ```json
 {
@@ -202,7 +235,7 @@ Send a question to the user via push notification and wait for their answer. By
 }
 ```
 
-**Example — input (free text):**
+**Example - input (free text):**
 
 ```json
 {
@@ -226,8 +259,8 @@ Poll for the user's response to a question sent via `ask_user` with `wait: false
 | timeoutMs | integer | No | How long to wait (default 30000, max 55000) |
 
 **Returns:**
-- `{ "answered": true, "value": "yes" }` — user responded
-- `{ "answered": false }` — timeout reached, no answer yet
+- `{ "answered": true, "value": "yes" }` - user responded
+- `{ "answered": false }` - timeout reached, no answer yet
 
 ### cancel_question
 
@@ -239,6 +272,50 @@ Cancel a pending question so it can no longer be answered. Use when the question
 |------|------|----------|-------------|
 | correlationId | string (uuid) | Yes | The correlationId of the question to cancel |
 
+### propose_scope
+
+Propose what a run will touch and block until the user ratifies it. Call **once**, at the start of a multi-step run, before doing work.
+
+The user sees the paths you intend to change, the areas you promise to leave alone, and your definition of done, and approves the whole thing in one tap. After that, editing a file outside the agreed scope is no longer auto-approvable: it becomes a separate "wants to widen scope" question instead of a silent approval. Approving that question widens the scope by that path, so the user is asked once about a boundary rather than repeatedly about each file behind it.
+
+Use glob syntax (`src/**`, `**/*.test.ts`). Shell commands are **not** scoped here; they stay governed by the permission policy.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| doneWhen | string | Yes | What "finished" means for this run. Carried for the human to judge against, never enforced automatically |
+| sessionId | string | Yes | Your per-session id. A scope with no session cannot be enforced and must never leak into another run |
+| allowedPaths | string[] | No | Globs you intend to change. Omit to propose no path restriction, which the user is told plainly |
+| offLimitsPaths | string[] | No | Globs you promise not to touch. These win wherever they overlap `allowedPaths` |
+| agentName | string | No | Name of the agent asking, format `"{Agent} - {project}"` |
+| timeoutMs | integer | No | How long this call blocks, max 55000 |
+
+**Returns:**
+- `{ "ratified": true, "answered": true, "value": "yes", "contract": {...} }` - the contract is live
+- `{ "ratified": false, "answered": true, "value": "no" }` - the user declined. Ask what scope they want; do **not** proceed as if they agreed
+- `{ "ratified": false, "answered": false }` - no answer yet. The scope is **not** in force
+
+**What enforcement depends on.** The contract is recorded and shown to the user by any MCP client. Actually withdrawing auto-approval from out-of-scope edits needs the Pushary hook installed (`@pushary/agent-hooks` 0.59.0 or later), which is how Claude Code, Codex and Gemini CLI run. Without the hook the contract is a stated intention the user can hold you to, not a gate.
+
+Scope lives for the session only and is never inherited by another run.
+
+**When not to use it.** A single quick edit does not need a scope. And do not propose a new scope mid-run to widen an old one: do the work and let the approval that follows widen it, which is what that flow is for.
+
+### list_sessions
+
+Read-only. Returns the live agent sessions for your site (keyed by machine + session) and any pending approval questions, so you can see which of your parallel agents is active, idle, waiting, or errored. Does NOT start, stop, or steer agents, and sends no notification. Useful when you are one of several agents and want to check whether another session is blocked on a question before acting.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| status | "active" / "idle" / "waiting" / "errored" | No | Filter to sessions with this computed status |
+| limit | integer | No | Max number of sessions to return, most recently seen first (1-100) |
+
+**Returns:**
+- `{ "sessions": [...], "pendingQuestions": [...] }` - current sessions and open questions for the site
+
 ## Permission Gating (REQUIRED)
 
 Before executing any of the following, you MUST call `ask_user` with type "confirm" and wait for approval. Do NOT proceed without an explicit "yes" from the user:
@@ -257,7 +334,7 @@ This is not optional. Treat it as a hard constraint, not a suggestion.
 
 ## Human-in-the-Loop Flow
 
-One tool call — `ask_user` blocks and returns the answer:
+One tool call - `ask_user` blocks and returns the answer:
 
 ```
 result = ask_user({
@@ -269,13 +346,15 @@ result = ask_user({
 })
 
 if result.answered:
-    // result.value = "JWT tokens" — proceed with the chosen approach
+    // result.value = "JWT tokens" - proceed with the chosen approach
 else:
-    // user did not respond — pick the safe default or notify and skip
+    // user did not respond - pick the safe default or notify and skip
 ```
 
 If the user answers in chat before the push response arrives, continue normally and call `cancel_question` with the `correlationId` to clean up.
 
+**A note on how long ask_user blocks:** the wait time and whether it blocks at all are governed by the site's delivery mode, which the user configures (you do not set it). In the default smart mode and push-only mode, ask_user blocks for the policy timeout; in notify-only mode it returns immediately with `answered: false` after sending the push. Always check `answered` rather than assuming the call blocked, and pass `timeoutMs` only when you need a shorter wait than the site policy.
+
 ## Identifying Your Agent
 
 Always pass `agentName` when you are one of multiple possible agents the user may be running. The user sees this in the notification title to know which agent is asking.
@@ -292,6 +371,6 @@ Always pass `agentName` when you are one of multiple possible agents the user ma
 - **Titles under 60 characters.** They get truncated on phone lock screens.
 - **Bodies under 200 characters.** Concise summaries, not full explanations.
 - **Max 3 notifications per task** unless the user explicitly requests more.
-- **Use context for detail.** Put file lists, error traces, and next steps in the context object — not the notification body.
+- **Use context for detail.** Put file lists, error traces, and next steps in the context object - not the notification body.
 - **Write questions as if talking to a busy person.** The user is on their phone, possibly away from their computer. Be specific: "Delete the 3 unused migration files?" is better than "Should I clean up?"
 - **Pick the right question type.** Use confirm for binary decisions, select when options are known, input when they are not.

package/dist/bin/pushary-connect.js

@@ -6,7 +6,7 @@ import {
   confirmAppConnection,
   connectDevice,
   printConnectInstructions
-} from "../chunk-QTC7SR6A.js";
+} from "../chunk-YMFZUXL5.js";
 import "../chunk-3EGEA4KH.js";
 import {
   readKeySource

package/dist/bin/pushary-doctor.js

@@ -35,7 +35,7 @@ import {
   describeReach,
   fetchChannels,
   reachVerdict
-} from "../chunk-QTC7SR6A.js";
+} from "../chunk-YMFZUXL5.js";
 import "../chunk-3EGEA4KH.js";
 import {
   keyPrefix,

package/dist/bin/pushary-setup.js

@@ -48,7 +48,7 @@ import {
   connectViaAppPairing,
   printConnectInstructions,
   setHumanStream
-} from "../chunk-QTC7SR6A.js";
+} from "../chunk-YMFZUXL5.js";
 import "../chunk-3EGEA4KH.js";
 import {
   KEY_FILE_MODE,

package/dist/bin/pushary-status.js

@@ -7,7 +7,7 @@ import {
   describeReach,
   fetchChannels,
   reachVerdict
-} from "../chunk-QTC7SR6A.js";
+} from "../chunk-YMFZUXL5.js";
 import "../chunk-3EGEA4KH.js";
 import {
   readKeySource

package/dist/{chunk-QTC7SR6A.js → chunk-YMFZUXL5.js}

@@ -54,6 +54,7 @@ var setHumanStream = (target) => {
 var writeHuman = (text) => {
   stream.write(text);
 };
+var humanIsTty = () => stream === process.stdout && process.stdout.isTTY === true;
 
 // src/onboarding.ts
 import qrcodeTerminal from "qrcode-terminal";
@@ -258,16 +259,59 @@ var fetchChannels = async (apiKey) => {
   };
 };
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var SPINNER_HEARTBEAT_MS = 3e4;
+var SPINNER_FRAME_MS = 200;
+var writeStatusLine = (text) => {
+  writeHuman(humanIsTty() ? `\r  ${text}\x1B[K
+` : `  ${text}
+`);
+};
+var visibleLength = (text) => text.replace(/\x1b\[[0-9;]*m/g, "").length;
+var clipToRow = (text, columns) => {
+  const budget = columns - 4;
+  if (budget <= 1 || visibleLength(text) <= budget) return text;
+  let visible = 0;
+  let out = "";
+  for (let i = 0; i < text.length; i += 1) {
+    const escape = /^\x1b\[[0-9;]*m/.exec(text.slice(i));
+    if (escape) {
+      out += escape[0];
+      i += escape[0].length - 1;
+      continue;
+    }
+    if (visible >= budget - 1) break;
+    out += text[i];
+    visible += 1;
+  }
+  return `${out}\u2026`;
+};
+var terminalColumns = () => {
+  const columns = process.stdout.columns;
+  return typeof columns === "number" && columns > 0 ? columns : 80;
+};
 var startSpinner = (getLabel) => {
+  if (!humanIsTty()) {
+    writeHuman(`  ${getLabel()}
+`);
+    const interval2 = setInterval(() => {
+      writeHuman(`  ${getLabel()}
+`);
+    }, SPINNER_HEARTBEAT_MS);
+    interval2.unref?.();
+    return (finalGlyph, finalLabel) => {
+      clearInterval(interval2);
+      writeStatusLine(`${finalGlyph} ${finalLabel}`);
+    };
+  }
   const frames = ["   ", ".  ", ".. ", "..."];
   let i = 0;
   const interval = setInterval(() => {
-    writeHuman(`\r  ${dim(frames[i++ % frames.length])} ${getLabel()}`);
-  }, 200);
+    const line = `${dim(frames[i++ % frames.length])} ${getLabel()}`;
+    writeHuman(`\r  ${clipToRow(line, terminalColumns())}\x1B[K`);
+  }, SPINNER_FRAME_MS);
   return (finalGlyph, finalLabel) => {
     clearInterval(interval);
-    writeHuman(`\r  ${finalGlyph} ${finalLabel}\x1B[K
-`);
+    writeStatusLine(`${finalGlyph} ${finalLabel}`);
   };
 };
 var printQr = (url) => new Promise((resolve, reject) => {
@@ -304,8 +348,7 @@ var waitForDevice = async (apiKey, baseline) => {
         consecutiveFailures += 1;
         if (consecutiveFailures >= 3 && !warned) {
           warned = true;
-          writeHuman(`\r  ${yellow("!")} Still trying. pushary.com is not answering ${dim(`(${probe.detail})`)}\x1B[K
-`);
+          writeStatusLine(`${yellow("!")} Still trying. pushary.com is not answering ${dim(`(${probe.detail})`)}`);
         }
         await sleep(CONNECT_POLL_INTERVAL_MS);
         continue;
@@ -319,6 +362,8 @@ var waitForDevice = async (apiKey, baseline) => {
       await sleep(CONNECT_POLL_INTERVAL_MS);
     }
     stop(yellow("!"), "Didn't detect a connection yet");
+    console.log(`  ${dim("Signed in on the app already? Open it and allow notifications.")}`);
+    console.log(`  ${dim("Signing in alone does not connect the phone. Then run")} ${cyan("pushary doctor")}${dim(".")}`);
     return { kind: "timeout" };
   } catch (err) {
     stop(yellow("!"), `Couldn't check connection ${dim(`(${err instanceof Error ? err.message : "network error"})`)}`);
@@ -465,6 +510,18 @@ var startPairing = async (cliPublicKey) => {
     return null;
   }
 };
+var describePairFailure = (reason) => {
+  switch (reason) {
+    case "no_site":
+      return "Couldn't set up your workspace. Try again, or finish setup at pushary.com/dashboard";
+    case "blocked":
+      return "Finish setting up in the Pushary app, then run setup again";
+    case "authorize_failed":
+      return "The app could not authorize this terminal. Re-run setup to try again";
+    default:
+      return "Pairing failed. Re-run setup to try again";
+  }
+};
 var cancelPairing = async (pairId) => {
   try {
     await fetch(`${apiBase()}/api/mobile/pair/start`, {
@@ -514,12 +571,19 @@ var connectViaAppPairing = async (options = {}) => {
   console.log();
   const startedAt = Date.now();
   const deadline = startedAt + PAIR_TIMEOUT_MS;
+  let hintShown = false;
   const stop = startSpinner(() => {
     const left = Math.max(0, Math.ceil((deadline - Date.now()) / 6e4));
     if (Date.now() - startedAt < PAIR_HINT_AFTER_MS) {
       return "Waiting for the app to authorize";
     }
-    return `Waiting for the app ${dim(`(${left}m left. No app yet? Install it, sign in with this account, then scan. Ctrl-C to stop)`)}`;
+    if (!hintShown) {
+      hintShown = true;
+      writeStatusLine(
+        `${dim("No app yet? Install it, sign in with this account, then scan. Ctrl-C to stop.")}`
+      );
+    }
+    return `Waiting for the app ${dim(`(${left}m left)`)}`;
   });
   let cancelled = false;
   const onInterrupt = () => {
@@ -549,6 +613,10 @@ var connectViaAppPairing = async (options = {}) => {
         stop(yellow("!"), "Pairing expired \u2014 re-run setup to try again");
         return null;
       }
+      if (claim?.status === "failed") {
+        stop(yellow("!"), describePairFailure(claim.reason));
+        return null;
+      }
       await sleep(PAIR_POLL_INTERVAL_MS);
     }
     stop(yellow("!"), "Timed out waiting for the app");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushary/agent-hooks",
-  "version": "0.67.0",
+  "version": "0.68.0",
   "description": "Permission hooks for AI coding agents: route tool approvals through Pushary push notifications",
   "keywords": [
     "pushary",
@@ -25,13 +25,8 @@
   ],
   "author": "Pushary <business@pushary.com>",
   "homepage": "https://pushary.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/pushary/pushary.git",
-    "directory": "packages/agent-hooks"
-  },
   "bugs": {
-    "url": "https://github.com/pushary/pushary/issues"
+    "url": "https://pushary.com/support"
   },
   "license": "MIT",
   "type": "module",