chore(release): cut 0.1.33

This reverts commit e36784e510.

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.33 - 2026-03-23
+
+### Fixed
+- Fixed the desktop app failing to reopen after closing on macOS — the daemon and agent processes were registering with Launch Services as instances of the main app, blocking subsequent launches.
+- Fixed dictation not working in the packaged desktop app — the microphone entitlement was missing from the hardened runtime configuration.
+- Fixed leaked Claude Code child processes when agents were closed — the SDK query stream was not being properly shut down.
+- The notification test button now surfaces errors instead of failing silently.
+
 ## 0.1.32 - 2026-03-23
 
 ### Added

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "paseo",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "paseo",
-      "version": "0.1.32",
+      "version": "0.1.33",
       "hasInstallScript": true,
       "license": "AGPL-3.0-or-later",
       "workspaces": [
@@ -34842,16 +34842,16 @@
     },
     "packages/app": {
       "name": "@getpaseo/app",
-      "version": "0.1.32",
+      "version": "0.1.33",
       "dependencies": {
         "@dnd-kit/core": "^6.3.1",
         "@dnd-kit/sortable": "^10.0.0",
         "@dnd-kit/utilities": "^3.2.2",
         "@expo/vector-icons": "^15.0.2",
         "@floating-ui/react-native": "^0.10.7",
-        "@getpaseo/expo-two-way-audio": "0.1.32",
-        "@getpaseo/highlight": "*",
-        "@getpaseo/server": "0.1.32",
+        "@getpaseo/expo-two-way-audio": "0.1.33",
+        "@getpaseo/highlight": "0.1.33",
+        "@getpaseo/server": "0.1.33",
         "@gorhom/bottom-sheet": "^5.2.6",
         "@gorhom/portal": "^1.0.14",
         "@react-native-async-storage/async-storage": "2.2.0",
@@ -34963,11 +34963,11 @@
     },
     "packages/cli": {
       "name": "@getpaseo/cli",
-      "version": "0.1.32",
+      "version": "0.1.33",
       "dependencies": {
         "@clack/prompts": "^1.0.0",
-        "@getpaseo/relay": "0.1.32",
-        "@getpaseo/server": "0.1.32",
+        "@getpaseo/relay": "0.1.33",
+        "@getpaseo/server": "0.1.33",
         "chalk": "^5.3.0",
         "commander": "^12.0.0",
         "mime-types": "^2.1.35",
@@ -35004,10 +35004,10 @@
     },
     "packages/desktop": {
       "name": "@getpaseo/desktop",
-      "version": "0.1.32",
+      "version": "0.1.33",
       "dependencies": {
-        "@getpaseo/cli": "0.1.32",
-        "@getpaseo/server": "0.1.32",
+        "@getpaseo/cli": "0.1.33",
+        "@getpaseo/server": "0.1.33",
         "electron-updater": "^6.6.2",
         "ws": "^8.14.2"
       },
@@ -35040,7 +35040,7 @@
     },
     "packages/expo-two-way-audio": {
       "name": "@getpaseo/expo-two-way-audio",
-      "version": "0.1.32",
+      "version": "0.1.33",
       "license": "MIT",
       "devDependencies": {
         "@biomejs/biome": "1.9.4",
@@ -35241,7 +35241,7 @@
     },
     "packages/highlight": {
       "name": "@getpaseo/highlight",
-      "version": "0.1.32",
+      "version": "0.1.33",
       "dependencies": {
         "@lezer/common": "^1.5.0",
         "@lezer/cpp": "^1.1.5",
@@ -35267,7 +35267,7 @@
     },
     "packages/relay": {
       "name": "@getpaseo/relay",
-      "version": "0.1.32",
+      "version": "0.1.33",
       "dependencies": {
         "base64-js": "^1.5.1",
         "tweetnacl": "^1.0.3",
@@ -35283,13 +35283,13 @@
     },
     "packages/server": {
       "name": "@getpaseo/server",
-      "version": "0.1.32",
+      "version": "0.1.33",
       "dependencies": {
         "@ai-sdk/openai": "2.0.52",
         "@anthropic-ai/claude-agent-sdk": "^0.2.11",
         "@deepgram/sdk": "^3.4.0",
-        "@getpaseo/highlight": "*",
-        "@getpaseo/relay": "0.1.32",
+        "@getpaseo/highlight": "0.1.33",
+        "@getpaseo/relay": "0.1.33",
         "@modelcontextprotocol/sdk": "^1.20.1",
         "@opencode-ai/sdk": "1.2.6",
         "@sctg/sentencepiece-js": "^1.1.0",
@@ -35637,7 +35637,7 @@
     },
     "packages/website": {
       "name": "@getpaseo/website",
-      "version": "0.1.32",
+      "version": "0.1.33",
       "dependencies": {
         "@cloudflare/vite-plugin": "^1.20.3",
         "@cloudflare/workers-types": "^4.20260114.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "private": true,
   "workspaces": [
     "packages/expo-two-way-audio",
@@ -44,9 +44,9 @@
     "version:all:patch": "npm version patch --include-workspace-root --message \"chore(release): cut %s\"",
     "version:all:minor": "npm version minor --include-workspace-root --message \"chore(release): cut %s\"",
     "version:all:major": "npm version major --include-workspace-root --message \"chore(release): cut %s\"",
-    "release:check": "npm run release:prepare && npm run typecheck --workspace=@getpaseo/relay && npm run typecheck --workspace=@getpaseo/server && npm run typecheck --workspace=@getpaseo/cli && npm run build --workspace=@getpaseo/relay && npm run build --workspace=@getpaseo/server && npm run build --workspace=@getpaseo/cli && npm pack --dry-run --workspace=@getpaseo/relay && npm pack --dry-run --workspace=@getpaseo/server && npm pack --dry-run --workspace=@getpaseo/cli",
-    "release:publish:dry-run": "npm publish --dry-run --workspace=@getpaseo/relay --access public && npm publish --dry-run --workspace=@getpaseo/server --access public && npm publish --dry-run --workspace=@getpaseo/cli --access public",
-    "release:publish": "npm publish --workspace=@getpaseo/relay --access public && npm publish --workspace=@getpaseo/server --access public && npm publish --workspace=@getpaseo/cli --access public",
+    "release:check": "npm run release:prepare && npm run typecheck --workspace=@getpaseo/highlight && npm run typecheck --workspace=@getpaseo/relay && npm run typecheck --workspace=@getpaseo/server && npm run typecheck --workspace=@getpaseo/cli && npm run build --workspace=@getpaseo/highlight && npm run build --workspace=@getpaseo/relay && npm run build --workspace=@getpaseo/server && npm run build --workspace=@getpaseo/cli && npm pack --dry-run --workspace=@getpaseo/highlight && npm pack --dry-run --workspace=@getpaseo/relay && npm pack --dry-run --workspace=@getpaseo/server && npm pack --dry-run --workspace=@getpaseo/cli",
+    "release:publish:dry-run": "npm publish --dry-run --workspace=@getpaseo/highlight --access public && npm publish --dry-run --workspace=@getpaseo/relay --access public && npm publish --dry-run --workspace=@getpaseo/server --access public && npm publish --dry-run --workspace=@getpaseo/cli --access public",
+    "release:publish": "npm publish --workspace=@getpaseo/highlight --access public && npm publish --workspace=@getpaseo/relay --access public && npm publish --workspace=@getpaseo/server --access public && npm publish --workspace=@getpaseo/cli --access public",
     "release:push": "node scripts/push-current-release-tag.mjs",
     "draft-release:push": "node scripts/push-current-release-tag.mjs --draft-release",
     "draft-release:patch": "npm run version:all:patch && npm run release:check && npm run draft-release:push",

packages/app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@getpaseo/app",
   "main": "index.ts",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "private": true,
   "scripts": {
     "start": "expo start",
@@ -31,9 +31,9 @@
     "@dnd-kit/utilities": "^3.2.2",
     "@expo/vector-icons": "^15.0.2",
     "@floating-ui/react-native": "^0.10.7",
-    "@getpaseo/expo-two-way-audio": "0.1.32",
-    "@getpaseo/highlight": "*",
-    "@getpaseo/server": "0.1.32",
+    "@getpaseo/expo-two-way-audio": "0.1.33",
+    "@getpaseo/highlight": "0.1.33",
+    "@getpaseo/server": "0.1.33",
     "@gorhom/bottom-sheet": "^5.2.6",
     "@gorhom/portal": "^1.0.14",
     "@react-native-async-storage/async-storage": "2.2.0",

packages/app/src/desktop/components/desktop-permissions-section.tsx

@@ -14,6 +14,7 @@ export function DesktopPermissionsSection() {
     isRefreshing,
     requestingPermission,
     isSendingTestNotification,
+    testNotificationError,
     refreshPermissions,
     requestPermission,
     sendTestNotification,
@@ -58,6 +59,11 @@ export function DesktopPermissionsSection() {
             void sendTestNotification();
           }}
         />
+        {testNotificationError ? (
+          <Text style={[styles.errorText, { color: theme.colors.danger }]}>
+            {testNotificationError}
+          </Text>
+        ) : null}
         <DesktopPermissionRow
           title="Microphone"
           showBorder
@@ -80,4 +86,9 @@ const styles = StyleSheet.create((theme) => ({
     gap: theme.spacing[2],
     marginBottom: theme.spacing[3],
   },
+  errorText: {
+    fontSize: theme.fontSize.xs,
+    paddingHorizontal: theme.spacing[4],
+    paddingBottom: theme.spacing[2],
+  },
 }));

packages/app/src/desktop/permissions/use-desktop-permissions.ts

@@ -14,6 +14,7 @@ export interface UseDesktopPermissionsReturn {
   isRefreshing: boolean;
   requestingPermission: DesktopPermissionKind | null;
   isSendingTestNotification: boolean;
+  testNotificationError: string | null;
   refreshPermissions: () => Promise<void>;
   requestPermission: (kind: DesktopPermissionKind) => Promise<void>;
   sendTestNotification: () => Promise<void>;
@@ -112,22 +113,25 @@ export function useDesktopPermissions(): UseDesktopPermissionsReturn {
     [isDesktop, refreshPermissions],
   );
 
+  const [testNotificationError, setTestNotificationError] = useState<string | null>(null);
+
   const sendTestNotification = useCallback(async () => {
     if (!isDesktop) {
       return;
     }
 
     setIsSendingTestNotification(true);
+    setTestNotificationError(null);
     try {
       const sent = await sendOsNotification({
         title: "Paseo notification test",
         body: "If you can see this, desktop notifications work.",
       });
       if (!sent) {
-        console.warn("[Settings] Desktop test notification was not delivered");
+        setTestNotificationError("Notification was not delivered. Check System Settings > Notifications.");
       }
     } catch (error) {
-      console.error("[Settings] Failed to send desktop test notification", error);
+      setTestNotificationError("Failed to send notification.");
     } finally {
       if (isMountedRef.current) {
         setIsSendingTestNotification(false);
@@ -149,6 +153,7 @@ export function useDesktopPermissions(): UseDesktopPermissionsReturn {
     isRefreshing,
     requestingPermission,
     isSendingTestNotification,
+    testNotificationError,
     refreshPermissions,
     requestPermission,
     sendTestNotification,

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/cli",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "Paseo CLI - control your AI coding agents from the command line",
   "type": "module",
   "files": [
@@ -24,8 +24,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.0",
-    "@getpaseo/relay": "0.1.32",
-    "@getpaseo/server": "0.1.32",
+    "@getpaseo/relay": "0.1.33",
+    "@getpaseo/server": "0.1.33",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "mime-types": "^2.1.35",

packages/desktop/build/entitlements.mac.inherit.plist

@@ -6,5 +6,7 @@
   <true/>
   <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
   <true/>
+  <key>com.apple.security.device.audio-input</key>
+  <true/>
 </dict>
 </plist>

packages/desktop/build/entitlements.mac.plist

@@ -6,5 +6,7 @@
   <true/>
   <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
   <true/>
+  <key>com.apple.security.device.audio-input</key>
+  <true/>
 </dict>
 </plist>

packages/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/desktop",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "private": true,
   "description": "Paseo desktop app (Electron wrapper)",
   "main": "dist/main.js",
@@ -12,8 +12,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@getpaseo/cli": "0.1.32",
-    "@getpaseo/server": "0.1.32",
+    "@getpaseo/cli": "0.1.33",
+    "@getpaseo/server": "0.1.33",
     "electron-updater": "^6.6.2",
     "ws": "^8.14.2"
   },

packages/desktop/src/daemon/runtime-paths.ts

@@ -168,6 +168,30 @@ export function resolveCliEntrypoint(): NodeEntrypointSpec {
   };
 }
 
+function resolveNodeExecPath(): string {
+  if (app.isPackaged && process.platform === "darwin") {
+    const marker = ".app/Contents/MacOS/";
+    const markerIndex = process.execPath.indexOf(marker);
+    if (markerIndex !== -1) {
+      const bundleRoot = process.execPath.substring(0, markerIndex + ".app".length);
+      const name = path.basename(process.execPath);
+      const helperPath = path.join(
+        bundleRoot,
+        "Contents",
+        "Frameworks",
+        `${name} Helper.app`,
+        "Contents",
+        "MacOS",
+        `${name} Helper`,
+      );
+      if (existsSync(helperPath)) {
+        return helperPath;
+      }
+    }
+  }
+  return process.execPath;
+}
+
 export function createNodeEntrypointInvocation(input: {
   entrypoint: NodeEntrypointSpec;
   argvMode: NodeEntrypointArgvMode;
@@ -175,7 +199,7 @@ export function createNodeEntrypointInvocation(input: {
   baseEnv: NodeJS.ProcessEnv;
 }): NodeEntrypointInvocation {
   return createSharedNodeEntrypointInvocation({
-    execPath: process.execPath,
+    execPath: resolveNodeExecPath(),
     isPackaged: app.isPackaged,
     packagedRunnerPath: app.isPackaged
       ? assertPathExists({

packages/expo-two-way-audio/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/expo-two-way-audio",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "Native module for two way audio streaming",
   "main": "build/index.js",
   "types": "build/index.d.ts",

packages/highlight/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@getpaseo/highlight",
-  "version": "0.1.32",
-  "private": true,
+  "version": "0.1.33",
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "main": "./dist/index.js",
-  "types": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{ recursive: true, force: true })\" && tsc -p tsconfig.json --incremental false",
     "prepack": "npm run build",

packages/relay/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/relay",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "Paseo relay for bridging daemon and client connections",
   "type": "module",
   "publishConfig": {

packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/server",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "Paseo backend server",
   "type": "module",
   "publishConfig": {
@@ -64,8 +64,8 @@
     "@ai-sdk/openai": "2.0.52",
     "@anthropic-ai/claude-agent-sdk": "^0.2.11",
     "@deepgram/sdk": "^3.4.0",
-    "@getpaseo/highlight": "*",
-    "@getpaseo/relay": "0.1.32",
+    "@getpaseo/highlight": "0.1.33",
+    "@getpaseo/relay": "0.1.33",
     "@modelcontextprotocol/sdk": "^1.20.1",
     "@opencode-ai/sdk": "1.2.6",
     "@sctg/sentencepiece-js": "^1.1.0",

packages/server/src/server/agent/providers/claude-agent.ts

@@ -1611,6 +1611,7 @@ class ClaudeAgentSession implements AgentSession {
     this.activeTurnPromise = null;
     this.sidechainTracker.clear();
     this.input?.end();
+    this.query?.close();
     await this.awaitWithTimeout(this.query?.interrupt?.(), "close query interrupt");
     await this.awaitWithTimeout(this.query?.return?.(), "close query return");
     this.query = null;
@@ -1877,6 +1878,7 @@ class ClaudeAgentSession implements AgentSession {
 
     if (this.queryRestartNeeded && this.query) {
       this.input?.end();
+      this.query.close();
       try {
         await this.query.return?.();
       } catch {

packages/website/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/website",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "private": true,
   "type": "module",
   "scripts": {

skills/paseo-orchestrator/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: paseo-orchestrator
+description: Orchestrate work through agents. Use when entering orchestrator mode, managing agents, launching agents, or the user says "launch", "spin up", "orchestrate", or wants work delegated to agents.
+user-invocable: true
+---
+
+# Orchestrator Mode
+
+You are an orchestrator. You manage agents — you do not write code yourself.
+
+## Prerequisites
+
+Load the **Paseo skill** first — it contains the CLI reference for all agent commands and waiting guidelines.
+
+## Your Role
+
+You have two audiences and you speak differently to each.
+
+**To the user** — you are a design partner. You discuss architecture, data shapes, interfaces, types, flow, and trade-offs. Code examples are your primary communication tool here. You help the user think through what they want and ensure their intent is clearly defined before agents start working.
+
+**To agents** — you are a product owner. You define acceptance criteria and behavioral expectations. You do NOT tell agents how to implement things — no "set variable X to Y", no "in file Z change line 42", no implementation-level code snippets. Agents read the codebase and figure out the implementation.
+
+Your job:
+1. **Understand the problem** — discuss with the user, explore the design space, propose types/interfaces/data shapes
+2. **Define acceptance criteria** — what does "done" look like from the user's perspective?
+3. **Launch agents** with clear, behavior-focused prompts
+4. **Course-correct** when agents drift
+5. **Review the output** — spin up a review agent to verify the work meets criteria
+6. **Report back** to the user with what was done and what to test
+
+You ensure the user's will is manifested through agents doing work.
+
+**You own your agents.** Every agent you launch is your responsibility. You wait for them, read their output, challenge their work, and ensure they deliver. You do not launch an agent and move on — you stay with it until the job is done. The only exception is when the user explicitly says it's fire-and-forget.
+
+## Before Launching Agents
+
+Before any agent starts working, align with the user on logistics:
+
+- **Where?** — Work in the current working directory unless the user specifies a worktree. Don't assume.
+- **What's the deliverable?** — Is the objective a PR? A commit? Just exploration with no edits? Ask if unclear.
+- **Is there a GitHub issue?** — Link it in the agent prompt if so. The agent should reference it.
+- **Does the user want proof?** — Screenshot? Video? Manual test? Automated test? Know what "verified" means for this task.
+
+These questions prevent wasted work. A perfectly implemented feature in the wrong branch or without a PR is still a failure.
+
+## Agent Types
+
+Implementation and review are not the only agent roles. Use the right agent for the job:
+
+- **Exploration agents** — Read the codebase, map dependencies, understand how something works. Launch these when you need context before making decisions.
+- **Investigation agents** — Debug a problem, trace a bug, find root cause. Must NOT edit files.
+- **Implementation agents** — Write code to meet acceptance criteria.
+- **Review agents** — Independently verify implementation meets criteria. Must NOT edit files.
+- **Second opinion agents** — When you're unsure about an approach, launch an agent (different provider if possible) to evaluate the plan and poke holes in it.
+
+Don't limit yourself to implement → review. Explore first if you need context. Get a second opinion if the design is tricky. The user is paying for thoroughness, not speed.
+
+## How to Write Agent Prompts
+
+This is the most important skill. A good prompt produces good work. A bad prompt produces wasted time.
+
+### Lead with behavior, not implementation details
+
+When writing prompts for agents, describe the problem and desired outcome. Never dictate implementation.
+
+**Bad** (micromanaging the agent):
+```
+Fix the cursor position in the autoformat handler. In `divider-autoformat.ts`,
+after the replacement edit, set the cursor to `dividerEnd + 1`. Use
+`applyEdit` with the new position.
+```
+
+This is bad because you're telling the agent WHICH file to edit, WHICH variable to set, and HOW to call the API. The agent will blindly follow your instructions even if they're wrong, instead of understanding the codebase and finding the right fix.
+
+**Good** (product owner defining behavior):
+```
+## Bug: Caret position after typing ---
+
+### What the user sees
+The user types three dashes on an empty line. A divider appears.
+The caret should now be blinking on a NEW EMPTY LINE below the divider,
+ready for the user to keep typing.
+
+### What actually happens
+The caret stays on or before the divider. The user has to manually
+press Enter to continue.
+
+### Acceptance criteria
+- Type ---, divider appears, caret is on a new empty paragraph BELOW
+- Works at end of document (new paragraph created)
+- Works in middle of document (caret on existing next line)
+- User can immediately start typing — no extra keystrokes needed
+```
+
+This is good because the agent understands the PROBLEM and can find the right solution itself.
+
+### Structure every prompt the same way
+
+Every agent prompt should have:
+
+1. **Context** — what repo, what feature, what's the current state
+2. **Problem** — what's wrong, described as user-visible behavior
+3. **Acceptance criteria** — specific, testable, behavioral statements
+4. **How to verify** — describe the test scenario, not the test code. Tell them WHAT to test, not HOW to write the test.
+5. **Constraints** — what they must NOT do (e.g., "do not bump version", "do not modify unrelated files")
+6. **Workflow** — TDD, commit expectations, what commands to run
+
+### Don't dictate implementation to agents
+
+Trust the agent to:
+- Find the right files
+- Choose the right approach
+- Write the right tests
+- Structure the code properly
+
+You tell them WHAT the user needs. They figure out HOW.
+
+But DO discuss implementation with the **user**. When the user asks about architecture, show them types, interfaces, data flow, code examples. That's how you align on design before agents start working.
+
+### Give complete context
+
+Agents start with **zero knowledge** of your conversation. Everything they need must be in the prompt. Don't assume they know:
+- What repo they're in (set cwd or tell them)
+- What feature was recently added
+- What decisions were made
+- What was already tried
+
+## Always Review
+
+After every implementation agent finishes, spin up a **review agent** to independently verify the work.
+
+The review agent should:
+- Check that all acceptance criteria are met — not by reading the agent's claims, but by actually testing
+- Verify tests exist and pass
+- Check that the agent didn't hand-wave or work around the problem
+- Flag any regressions
+- Run typecheck and tests
+
+```bash
+paseo run --provider codex --mode full-access --name "[Review] Task description" \
+  "Review the recent changes in [repo]. The goal was [goal].
+
+Acceptance criteria:
+- [criterion 1]
+- [criterion 2]
+
+Verify EACH criterion independently. Run the tests. Run typecheck.
+Check that the implementation actually solves the problem — not that
+it appears to solve it. Look for workarounds, hand-waves, and missing
+edge cases.
+
+DO NOT edit any files. Report your findings."
+```
+
+Don't skip this step. Don't trust the implementation agent's self-assessment.
+
+## Course-Correcting Agents
+
+When an agent goes off track, send a follow-up via `paseo send`:
+
+- Be specific about what's wrong
+- Restate the acceptance criteria they're missing
+- Don't give code fixes — describe the behavioral gap
+
+```bash
+paseo send <id> "The caret is still not on a new line after the divider.
+Re-read the acceptance criteria: the user must be able to immediately
+start typing on the line AFTER the divider without pressing Enter.
+Whatever you did didn't achieve that. Try again."
+```
+
+## Challenging Agents
+
+Agents lie, hand-wave, over-engineer, work around problems, solve the wrong thing, and don't check deeply enough. This is not occasional — it is the default. Your job is to catch it.
+
+### The behaviors to watch for
+
+- **Hand-waving** — Agent claims the fix works but didn't actually test the specific scenario. "Tests pass" doesn't mean the right tests exist.
+- **Over-engineering** — Agent adds abstractions, helper functions, configuration layers, or generalization that wasn't asked for. Simple problem, simple fix.
+- **Working around the problem** — Agent avoids the actual bug by adding a special case, a fallback, or a guard clause that masks the symptom instead of fixing the cause.
+- **Lying** — Agent says "all tests pass" when they didn't run them, or "I verified this works" when they checked something else entirely.
+- **Not checking deep enough** — Agent fixes the surface symptom without understanding why it happened. The fix works for the reported case but breaks in related scenarios.
+- **Being confused** — Agent misunderstands the problem and solves something different from what was asked.
+- **Solving the wrong thing** — Agent picks up on a secondary detail and optimizes that instead of addressing the core ask.
+
+### How to catch it
+
+Challenge agents by asking questions via `paseo send`:
+
+- "What exactly did you change and why?"
+- "What about [edge case X]? Did you test that?"
+- "Have you considered [alternative approach Y]?"
+- "Show me the test that covers [specific scenario]"
+- "Why did you add [abstraction/helper/config]? Was that necessary?"
+- "Is this fixing the root cause or masking the symptom?"
+- "Walk me through the data flow after your change"
+
+Don't accept the first answer. Push back. Ask follow-ups. The agent will refine its work when challenged.
+
+### User signals
+
+When the user says things like:
+- **"simplify"** — the agent over-engineered
+- **"think harder"** — the agent was shallow or confused
+- **"I don't like this"** — the agent solved the wrong thing or worked around the problem
+- **"this is wrong"** — the agent lied or didn't check deeply enough
+
+These are signals to challenge the agent, not to tweak the implementation yourself. Send the user's concern to the agent as a question, or spin up a review agent specifically looking for the pattern the user flagged.
+
+## Common Orchestrator Failures
+
+These are the patterns that lead to bad outcomes. Avoid them.
+
+### Micromanaging agents
+
+**Symptom:** Your agent prompts contain implementation directives — "set variable X to Y", "modify file Z", "this function is wrong, change it to...". You're telling the agent HOW to code instead of WHAT the user needs.
+
+**Fix:** Describe the behavior and acceptance criteria. The agent reads the codebase and finds the right approach. When you dictate implementation, the agent follows your instructions blindly — even when they're wrong — instead of using its own understanding of the code.
+
+Note: discussing architecture, types, interfaces, and code examples with the **user** is not micromanaging — that's your design partner role.
+
+### Skipping review
+
+**Symptom:** Agent says "done", you tell the user "done", user finds bugs.
+
+**Fix:** Always spin up a review agent. The implementation agent will claim success even when the fix is incomplete. Independent verification catches this.
+
+### Hand-waving acceptance criteria
+
+**Symptom:** "Fix the selection bug" with no behavioral definition of what "fixed" means.
+
+**Fix:** Define exactly what the user should see. Be specific enough that someone who has never seen the app could verify it.
+
+### Giving up on verification
+
+**Symptom:** "The agent says tests pass" without checking what the tests actually test.
+
+**Fix:** Tell the review agent what scenarios to verify. Design the test cases yourself (as a product owner) and tell the reviewer to check they exist.
+
+### Anxious polling
+
+**Symptom:** Agent is running, you start checking `paseo ls`, `paseo inspect`, `paseo logs` in a loop.
+
+**Fix:** `paseo wait`. Trust it. Agents can take 30+ minutes. This is normal.
+
+### Not providing feedback loops
+
+**Symptom:** Launch agent, wait, get result, launch new agent for next issue. Never send follow-ups.
+
+**Fix:** Use `paseo send` to course-correct running agents. They retain context. A follow-up is cheaper than a fresh agent.
+
+### Being too passive
+
+**Symptom:** Agent delivers something that doesn't quite match what the user wanted. You accept it and report back.
+
+**Fix:** Push back. Send follow-ups. Restate criteria. Don't accept work that doesn't meet the bar. You're the quality gate.
+
+## Clarifying Ambiguous Requests
+
+When user requests are unclear:
+
+1. **Research first** — spawn an investigation agent to understand the current state
+2. **Ask clarifying questions** — after research, ask the user specific questions
+3. **Present options** — offer approaches with trade-offs
+4. **Get explicit confirmation** — never assume what the user wants
+
+## Investigation vs Implementation
+
+When asked to investigate:
+
+- **Investigation agents MUST NOT fix issues** — they only identify, document, and report
+- **Always ask for confirmation** — after investigation, present findings and ask: "Should I proceed with implementing fixes?"
+- **Only implement if explicitly requested**
+
+## Workflow
+
+A typical orchestration cycle:
+
+1. User describes what they want
+2. You clarify if needed
+3. You launch an implementation agent with behavioral acceptance criteria
+4. You wait for it to finish
+5. You launch a review agent to verify
+6. If review passes → report to user
+7. If review fails → send corrections to impl agent or launch a new one
+8. Repeat until acceptance criteria are met
+
+## Multi-Agent Coordination
+
+When a task has independent parts:
+
+- Launch agents in parallel with `paseo run -d`
+- Each agent gets its own clear scope and acceptance criteria
+- Wait for all to finish
+- Review the combined output
+
+When tasks are sequential:
+
+- One agent at a time
+- Feed the output/state from one into the next agent's prompt
+- Review at the end
+
+## Prefix Convention
+
+Name all orchestrated agents with a prefix that indicates their role:
+
+- `[Impl]` — implementation agents
+- `[Review]` — review/verification agents
+- `[Investigate]` — research/investigation agents
+- `[Committee]` — committee planning agents
+- `[Handoff]` — handoff agents

skills/paseo/SKILL.md

@@ -1,11 +1,9 @@
 ---
 name: paseo
-description: Use when entering orchestrator mode to manage agents via Paseo CLI
+description: Paseo CLI reference for managing agents. Load this skill whenever you need to use paseo commands.
 ---
 
-### Paseo CLI Commands
-
-Use these CLI commands to manage agents:
+## CLI Commands
 
 ```bash
 # List agents (directory-scoped by default)
@@ -78,86 +76,31 @@ paseo ls --json          # JSON output
 paseo ls -q              # IDs only (quiet mode, useful for scripting)
 ```
 
-### Available Models
+## Available Models
 
-**Claude (default provider)** - use aliases, CLI resolves to latest version:
-- `--model haiku` - Fast/cheap, ONLY for tests (not for real work)
-- `--model sonnet` - Default, good for most tasks
-- `--model opus` - For harder reasoning, complex debugging
+**Claude (default provider)** — use aliases, CLI resolves to latest version:
+- `--model haiku` — Fast/cheap, ONLY for tests (not for real work)
+- `--model sonnet` — Default, good for most tasks
+- `--model opus` — For harder reasoning, complex debugging
 
 **Codex** (`--provider codex`):
-- `--model gpt-5.4` - Latest frontier agentic coding model (default, preferred for all engineering tasks)
-- `--model gpt-5.1-codex-mini` - Cheaper, faster, but less capable
+- `--model gpt-5.4` — Latest frontier agentic coding model (default, preferred for all engineering tasks)
+- `--model gpt-5.1-codex-mini` — Cheaper, faster, but less capable
 
-### Permissions
+## Permissions
 
 Always launch agents fully permissioned. Use `--mode bypass` for Claude and `--mode full-access` for Codex. Control behavior through **strict prompting**, not permission modes.
 
-### Agent Use Cases
+## Waiting for Agents
 
-You can run agents to:
-- **Implement a task** - Spawn an agent to write code and implement features
-- **Have a design discussion** - Use Codex for architecture discussions
-- **Test some feature** - Run tests and verify functionality
-- **Do investigation** - Research and explore the codebase
-- **Review changes** - Use Codex for thorough code reviews
-
-### Clarifying Ambiguous Requests
-
-**CRITICAL:** When user requests are ambiguous or unclear:
-
-1. **Research first** - Spawn an investigation agent to understand the current state
-2. **Ask clarifying questions** - After research, ask the user specific questions about what they want
-3. **Present options** - Offer multiple approaches with trade-offs
-4. **Get explicit confirmation** - Never assume what the user wants
-
-### Investigation vs Implementation
-
-**CRITICAL:** When asked to investigate:
-
-- **Investigation agents MUST NOT fix issues** - They should only identify, document, and report problems
-- **Always ask for confirmation** - After investigation, present findings and ask: "Should I proceed with implementing fixes?"
-- **Only implement if explicitly requested** - Don't auto-fix without user approval
-
-### Rigorous Agent Interrogation
-
-**CRITICAL:** Agents start with ZERO context about your task. You must always provide complete context in your initial prompt.
-
-When working with agents, you must dig deep and challenge them rigorously:
-
-#### For Implementation Agents
-
-- **Don't accept surface-level completion**: Check their logs with `paseo logs <id>`
-- **Trace the implementation**: Ask them to walk through the code flow step by step
-- **Uncover gaps**: Send follow-up prompts with `paseo send <id> "<question>"`
-  - "Show me exactly where you handle error case X"
-  - "What happens if the user does Y before Z?"
-  - "Walk me through the data flow from input to output"
-
-#### For Investigation/Debugging Agents
-
-- **Don't stop at the first answer**: Keep digging deeper
-- **Explore different angles**: "What are 3 other possible causes?"
-- **Request proof**: "Show me the specific code that proves this hypothesis"
-- **Challenge assumptions**: "How do you know that's the root cause?"
-
-#### For Review Agents (prefer Codex)
-
-- **Security review**: "What are the security implications? Any OWASP vulnerabilities?"
-- **Edge cases**: "What edge cases are not handled?"
-- **Performance**: "Where are the performance bottlenecks?"
-- **Maintainability**: "How maintainable is this code?"
-
-### Waiting for Agents
-
-**CRITICAL:** Both `paseo run` and `paseo wait` block until the agent completes. Trust them.
+Both `paseo run` and `paseo wait` block until the agent completes. Trust them.
 
 - `paseo run` waits **forever** by default (no timeout). Use `--wait-timeout` to set a limit.
 - `paseo wait` also waits forever by default. Use `--timeout` to set a limit.
 - Agent tasks can legitimately take 10, 20, or even 30+ minutes. This is normal.
 - When a wait times out, **just re-run `paseo wait <id>`** — don't panic, don't start checking logs, don't inspect status. The agent is still working.
-- Do NOT poll with `paseo ls`, `paseo inspect`, or `paseo logs` in a loop to "check on" the agent. This wastes your context window and accomplishes nothing.
-- Only check logs/inspect if you have a **specific reason** to believe something is wrong (e.g., you sent a prompt and got an unexpected error back).
+- Do NOT poll with `paseo ls`, `paseo inspect`, or `paseo logs` in a loop to "check on" the agent.
+- Only check logs/inspect if you have a **specific reason** to believe something is wrong.
 - **Never launch a duplicate agent** because a wait timed out. The original is still running.
 
 ```bash
@@ -166,35 +109,14 @@ paseo wait <id>              # timed out? just run it again:
 paseo wait <id>              # still going? keep waiting:
 paseo wait <id> --timeout 300  # or use a longer timeout
 
-# For long-running tasks, set a generous timeout on run itself:
-paseo run --wait-timeout 1h --output-schema '...' "<prompt>"
-
 # Wrong: anxious polling loop
 paseo wait <id>    # timed out
 paseo ls           # is it still running??
 paseo inspect <id> # what's it doing??
 paseo logs <id>    # let me check the logs!!
-# ^ Don't do this. Trust the wait.
 ```
 
-### Agent Management Principles
-
-- **Keep agents focused** - Each agent should have a clear, specific responsibility
-- **You can talk to them** - Use `paseo send <id> "<prompt>"` to guide them
-- **Monitor progress** - Use `paseo logs <id> -f` to stream output
-- **Always provide context** - Remember: agents start with zero knowledge of your task
-- **Verify work rigorously** - Don't trust, verify. Ask agents to prove their work
-- **Commit frequently** - Ensure each agent commits their changes before moving on
-- **Plan for quality gates** - Use Codex review agents as checkpoints
-- **Run in parallel when possible** - Use `-d` flag to run multiple agents concurrently
-
-### Common Patterns
-
-#### Committee
-
-When stuck or planning something hard, use the `/committee` skill. It launches two high-reasoning agents (Opus 4.6 + GPT 5.4) in parallel to do root cause analysis and produce a plan, then stays alive to review the implementation afterward.
-
-### Composing Agents in Bash Scripts
+## Composing Agents in Bash
 
 `paseo run` blocks by default and `--output-schema` returns structured JSON, making it easy to compose agents in bash loops and pipelines.
 
@@ -220,7 +142,4 @@ ui_id=$(paseo run -d --name "UI impl" "implement the UI" -q)
 # Wait for both to finish
 paseo wait "$api_id"
 paseo wait "$ui_id"
-
-# Review the combined result
-paseo run --provider codex "review the API and UI implementations. DO NOT edit."
 ```