@paneui/cli 0.0.3 → 0.0.5

package/dist/commands/artifact.js

@@ -1,7 +1,8 @@
 // `pane artifact` — manage reusable, versioned artifacts.
 //
 // Flat command namespace: `artifact` is one top-level command that branches on
-// a positional subcommand (create / version / update / search / list / show).
+// a positional subcommand (create / version / update / search / list / show /
+// delete).
 // An artifact is a reusable UI template (HTML + event schema + optional input
 // schema); a session is one *use* of one version of it. Authoring an artifact
 // once and instancing it via `pane create --artifact-id` removes the per-use
@@ -27,6 +28,9 @@ Subcommands:
   search     Search the agent's named artifacts (lean — no HTML).
   list       List the agent's named artifacts (search with no query).
   show       Show a full artifact: head metadata + its version list.
+  delete     Permanently delete an artifact and ALL its versions. Requires
+             --yes. Refused with 409 conflict if any session (open or
+             closed) still references the artifact — delete those first.
 
   pane artifact create --name <n> --artifact <path|inline>
                        [--event-schema <path|json>] [--slug <s>]
@@ -54,6 +58,13 @@ Subcommands:
   pane artifact show <id|slug>
       Prints the full artifact: head metadata + every version's content.
 
+  pane artifact delete <id|slug> --yes
+      Permanently deletes the artifact and all its versions. Refused
+      (409 conflict) if any session in any state still references one
+      of the artifact's versions — run 'pane delete <session-id>' on
+      each first, or wait for the relay's TTL sweeper to reclaim them.
+      Prints { artifact, deleted: true } on success.
+
 Options:
   --name <n>          Artifact display name (required for 'create').
   --slug <s>          Stable, agent-chosen handle (unique per agent). The
@@ -301,6 +312,28 @@ async function runArtifactShow(args) {
         failFromError(e);
     }
 }
+// `pane artifact delete <id|slug> --yes` — remove an artifact (and, server-
+// side, all its versions). The relay refuses with 409 conflict if any
+// session still references it; the CLI surfaces that as the relay-supplied
+// envelope. `--yes` is required because there's no Undo button on a delete
+// and the same `pane artifact create` slug isn't reservable once gone.
+async function runArtifactDelete(args) {
+    const idOrSlug = args.positionals[1];
+    if (!idOrSlug) {
+        fail("missing artifact <id|slug> — usage: pane artifact delete <id|slug> --yes", "invalid_args");
+    }
+    if (!args.bools.has("yes")) {
+        fail("'pane artifact delete' permanently removes the artifact and all its versions — it is destructive. Pass --yes to confirm.", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        await client.deleteArtifact(idOrSlug);
+        printJson({ artifact: idOrSlug, deleted: true });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
 export async function runArtifact(args) {
     const sub = args.positionals[0];
     switch (sub) {
@@ -322,10 +355,13 @@ export async function runArtifact(args) {
         case "show":
             await runArtifactShow(args);
             break;
+        case "delete":
+            await runArtifactDelete(args);
+            break;
         case undefined:
-            fail("missing subcommand — usage: pane artifact <create|version|update|search|list|show> (run 'pane artifact --help')", "invalid_args");
+            fail("missing subcommand — usage: pane artifact <create|version|update|search|list|show|delete> (run 'pane artifact --help')", "invalid_args");
             break;
         default:
-            fail(`unknown artifact subcommand '${sub}' — expected create|version|update|search|list|show (run 'pane artifact --help')`, "invalid_args");
+            fail(`unknown artifact subcommand '${sub}' — expected create|version|update|search|list|show|delete (run 'pane artifact --help')`, "invalid_args");
     }
 }

package/dist/commands/create.js

@@ -3,6 +3,42 @@ import { createSessionSchema } from "@paneui/core";
 import { makeClient } from "../config.js";
 import { resolveJson, resolveText } from "../input.js";
 import { printJson, fail, failFromError } from "../output.js";
+// Translate a Zod schema path (e.g. ["participants","humans"]) back to the
+// public CLI flag the user actually typed. Without this, a `--participants 0`
+// rejection surfaces as `participants.humans: ...` — which leaks the wire
+// shape and refers to no flag the user could fix.
+//
+// Match strategy: longest prefix wins. Schema paths whose top segment isn't
+// in the table fall back to dotted notation so we degrade gracefully on
+// fields that don't have a single corresponding flag (e.g. `artifact.source`
+// — there's no single --artifact-source flag for the inline form, just
+// --artifact pointing at the whole blob).
+const SCHEMA_PATH_TO_FLAG = {
+    participants: "--participants",
+    "participants.humans": "--participants",
+    ttl: "--ttl",
+    metadata: "--metadata",
+    callback: "--callback",
+    input_data: "--input-data",
+    "artifact.id": "--artifact-id",
+    "artifact.version": "--version",
+    "artifact.type": "--artifact-type",
+    "artifact.source": "--artifact",
+    "artifact.event_schema": "--event-schema",
+};
+function schemaPathToFlag(path) {
+    const dotted = path.map(String).join(".");
+    // Longest prefix that has a mapping. Try the full path first, then strip
+    // one trailing segment at a time. Falls back to dotted notation as the
+    // honest default.
+    for (let i = path.length; i > 0; i--) {
+        const prefix = path.slice(0, i).map(String).join(".");
+        const flag = SCHEMA_PATH_TO_FLAG[prefix];
+        if (flag !== undefined)
+            return flag;
+    }
+    return dotted;
+}
 export const createHelp = `pane create — create a Pane session
 
 A session is one use of an artifact. Supply the artifact in ONE of two ways:
@@ -184,7 +220,7 @@ export async function runCreate(args) {
     const parsed = createSessionSchema.safeParse(candidate);
     if (!parsed.success) {
         const issue = parsed.error.issues[0];
-        const where = issue && issue.path.length > 0 ? issue.path.join(".") : "request";
+        const where = issue && issue.path.length > 0 ? schemaPathToFlag(issue.path) : "request";
         fail(`invalid create request: ${where}: ${issue ? issue.message : "validation failed"}`, "invalid_args", parsed.error.flatten());
     }
     const req = parsed.data;

package/dist/commands/feedback.js

@@ -0,0 +1,127 @@
+import { makeClient } from "../config.js";
+import { printJson, fail, failFromError } from "../output.js";
+export const feedbackHelp = `pane feedback — submit / list feedback to the relay operator
+
+Feedback is a one-shot bug report, feature request, or note from YOUR agent
+to whoever runs the relay. Submissions are stored in the relay DB; the
+operator triages out of band.
+
+Usage:
+  pane feedback <subcommand> [options]
+
+Subcommands:
+  create     Submit one feedback row. Requires --type and --message.
+             Prints { id, type, created_at } — the message is not echoed back.
+
+  list       List YOUR agent's own submissions, newest first. Prints
+             { items: [...], next_before?: <cursor> }. Pass --before <cursor>
+             from a previous page to fetch the next page.
+
+Options for 'create':
+  --type <bug|feature|note>   Feedback category. Required.
+  --message <text|->          Message body. Pass '-' to read from stdin.
+                              1..4000 chars after trim.
+  --session-id <id>           Optional session this feedback relates to;
+                              must belong to YOUR agent.
+
+Options for 'list':
+  --limit <N>                 Page size (default 50, max 100).
+  --before <cursor>           Opaque cursor from a previous page's next_before.
+
+Global:
+  --url <url>                 Relay base URL (overrides PANE_URL).
+  --api-key <key>             Agent API key (overrides PANE_API_KEY).
+  -h, --help                  Show this help.
+
+Examples:
+  pane feedback create --type bug --message "watch hangs on empty session"
+  echo "long-form note..." | pane feedback create --type note --message -
+  pane feedback list --limit 20
+
+Output: stdout is machine-readable JSON.`;
+const FEEDBACK_TYPES = ["bug", "feature", "note"];
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function runFeedbackCreate(args) {
+    const type = args.flags.get("type");
+    const rawMessage = args.flags.get("message");
+    const sessionId = args.flags.get("session-id");
+    if (type === undefined) {
+        fail("'pane feedback create' requires --type <bug|feature|note>", "invalid_args");
+    }
+    if (!FEEDBACK_TYPES.includes(type)) {
+        fail(`unknown --type '${type}' — expected one of: ${FEEDBACK_TYPES.join(", ")}`, "invalid_args");
+    }
+    if (rawMessage === undefined) {
+        fail("'pane feedback create' requires --message <text|-> (use '-' to read from stdin)", "invalid_args");
+    }
+    let message;
+    if (rawMessage === "-") {
+        if (process.stdin.isTTY) {
+            fail("'pane feedback create --message -' expects feedback on stdin, but stdin is a TTY", "invalid_args");
+        }
+        message = await readStdin();
+    }
+    else {
+        message = rawMessage;
+    }
+    if (message.trim().length === 0) {
+        fail("feedback message must not be empty or whitespace-only", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const res = await client.submitFeedback({
+            type: type,
+            message,
+            ...(sessionId !== undefined ? { sessionId } : {}),
+        });
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runFeedbackList(args) {
+    const limitRaw = args.flags.get("limit");
+    const before = args.flags.get("before");
+    let limit;
+    if (limitRaw !== undefined) {
+        const n = Number(limitRaw);
+        if (!Number.isInteger(n) || n <= 0) {
+            fail(`--limit must be a positive integer, got '${limitRaw}'`, "invalid_args");
+        }
+        limit = n;
+    }
+    const client = makeClient(args);
+    try {
+        const page = await client.listFeedback({
+            ...(limit !== undefined ? { limit } : {}),
+            ...(before !== undefined ? { before } : {}),
+        });
+        printJson(page);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+export async function runFeedback(args) {
+    const sub = args.positionals[0];
+    switch (sub) {
+        case "create":
+            await runFeedbackCreate(args);
+            break;
+        case "list":
+            await runFeedbackList(args);
+            break;
+        case undefined:
+            fail("missing subcommand — usage: pane feedback <create|list> (run 'pane feedback --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown feedback subcommand '${sub}' — expected create|list (run 'pane feedback --help')`, "invalid_args");
+    }
+}

package/dist/commands/register.js

@@ -7,8 +7,9 @@
 // works with only PANE_URL (or nothing) set.
 import { registerAgent, PaneApiError } from "@paneui/core";
 import { DEFAULT_RELAY_URL } from "../config.js";
-import { printJson, fail } from "../output.js";
+import { printJson, fail, failUpgradeRequired } from "../output.js";
 import { readStore, writeStore } from "../store.js";
+import { VERSION } from "../version.js";
 export const registerHelp = `pane register — register this agent with the relay and save the key locally
 
 Usage:
@@ -48,10 +49,17 @@ export async function runRegister(args) {
             url: url.replace(/\/$/, ""),
             ...(name !== undefined ? { name } : {}),
             ...(secret !== undefined && secret !== "" ? { secret } : {}),
+            cliVersion: VERSION,
         });
     }
     catch (e) {
         if (e instanceof PaneApiError) {
+            // 426 cli_upgrade_required goes through the shared upgrade-message
+            // path (stderr block + exit 75) so the SKILL.md's instructions to the
+            // agent's harness fire on `pane register` too.
+            if (e.status === 426 && e.code === "cli_upgrade_required") {
+                failUpgradeRequired(e);
+            }
             if (e.status === 429) {
                 fail("registration rate limit exceeded — try again later", "rate_limited", undefined, { hint: e.hint, retryable: e.retryable, docs_url: e.docsUrl });
             }

package/dist/commands/skill.js

@@ -0,0 +1,136 @@
+// `pane skill` — fetch the relay's SKILL.md, or just its version.
+//
+// The relay serves its skill at GET /skills/pane/SKILL.md and its version
+// at GET /skills/pane/SKILL.md/version (see
+// packages/relay/src/http/routes/skill.ts). The skill is auto-updating:
+// the relay's deployed image owns both the body and the version, so the
+// agent always reads what the relay it's actually talking to wants it
+// to read.
+//
+// Two subcommands:
+//   `pane skill`           — print the full markdown to stdout (the
+//                            install / refresh path; pipe to a file).
+//   `pane skill version`   — print just the relay's skill version (the
+//                            "is my local copy stale?" probe). The agent
+//                            compares this to the `<!-- pane skill v… -->`
+//                            comment in its local skill file and re-runs
+//                            `pane skill > <path>` when they differ.
+//
+// Both are unauthenticated — the skill route is public on the relay and
+// an agent on a too-old CLI must be able to read the upgrade instructions
+// even before it has registered (or before its key was minted).
+import { resolveRelayUrl } from "../config.js";
+import { fail } from "../output.js";
+import { VERSION } from "../version.js";
+export const skillHelp = `pane skill — fetch the relay's SKILL.md (or its version)
+
+Usage:
+  pane skill                          Print the full skill to stdout.
+  pane skill version [--plain]        Print just the relay's skill version.
+
+The skill is auto-updating: the relay's deployed image owns the version,
+so this is always the skill that matches the relay you are talking to.
+
+Unauthenticated — no API key needed. An agent can call either form
+before 'pane register' to bootstrap or refresh its local skill copy.
+
+Subcommands:
+  (bare)              Fetch GET /skills/pane/SKILL.md and write the raw
+                      markdown to stdout. Pipe to your local skill path:
+                          pane skill > ~/.claude/skills/pane/SKILL.md
+  version             Fetch GET /skills/pane/SKILL.md/version and print
+                      the relay's skill version. Default output is the
+                      JSON envelope; --plain prints just the version
+                      string so an agent can compare it inline in shell.
+
+Options:
+  --plain             (with 'version' only) print the bare version
+                      string on stdout, no JSON envelope. Useful inside
+                      a shell pipeline: \`if [ "$(pane skill version
+                      --plain)" != "$LOCAL" ]; then ...\`.
+  --url <url>         Relay base URL (overrides PANE_URL).
+  -h, --help          Show this help.
+
+Output (stdout):
+  (bare)              Raw markdown, as served by the relay.
+  version             { "version": "1.0.0" } — or '1.0.0\\n' with --plain.
+
+Errors (stderr): { "error": { "code", "message" } } and non-zero exit.`;
+// Shared fetch with the consistent x-pane-cli-version header (the skill
+// routes are exempt from the version-skew middleware, but sending it lets
+// access logs see which CLI versions are reading the skill).
+async function fetchOrFail(url) {
+    try {
+        return await fetch(url, {
+            headers: { "x-pane-cli-version": VERSION },
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        fail(`could not reach ${url}: ${msg}`, "fetch_error");
+    }
+}
+async function failOnNon2xx(res, target) {
+    if (res.ok)
+        return;
+    // 404 if the operator stripped the route, 5xx on a static-read failure.
+    // Surface the body inline — it may carry a useful message.
+    const body = await res.text().catch(() => "");
+    fail(`relay returned ${res.status} for ${target}${body ? ": " + body.slice(0, 200) : ""}`, "relay_error");
+}
+// `pane skill` (no positional) — print the full skill.
+async function runSkillFetch(args) {
+    const url = resolveRelayUrl(args);
+    const target = url + "/skills/pane/SKILL.md";
+    const res = await fetchOrFail(target);
+    await failOnNon2xx(res, target);
+    const text = await res.text();
+    process.stdout.write(text);
+    // Ensure the markdown ends with a newline so a pipe-reader (cat | xargs |
+    // claude) sees a clean line-terminated boundary even if the relay served
+    // a file without a trailing newline.
+    if (!text.endsWith("\n"))
+        process.stdout.write("\n");
+}
+// `pane skill version [--plain]` — print just the version.
+async function runSkillVersion(args) {
+    const url = resolveRelayUrl(args);
+    const target = url + "/skills/pane/SKILL.md/version";
+    const res = await fetchOrFail(target);
+    await failOnNon2xx(res, target);
+    // The relay returns { version: "x.y.z" }. We tolerate a missing/
+    // malformed body so a misbehaving relay can't crash this probe — fall
+    // through to "0.0.0" the same way the relay does when its own SKILL.md
+    // lacks a version comment.
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        body = null;
+    }
+    const version = body !== null &&
+        typeof body === "object" &&
+        typeof body.version === "string"
+        ? body.version
+        : "0.0.0";
+    if (args.bools.has("plain")) {
+        process.stdout.write(version + "\n");
+    }
+    else {
+        process.stdout.write(JSON.stringify({ version }) + "\n");
+    }
+}
+export async function runSkill(args) {
+    const sub = args.positionals[0];
+    switch (sub) {
+        case undefined:
+            await runSkillFetch(args);
+            break;
+        case "version":
+            await runSkillVersion(args);
+            break;
+        default:
+            fail(`unknown skill subcommand '${sub}' — expected 'version' or no subcommand (run 'pane skill --help')`, "invalid_args");
+    }
+}

package/dist/commands/state.js

@@ -1,4 +1,4 @@
-// `pane state <id>` — non-blocking snapshot of a session.
+// `pane state <id>` — snapshot of a session, optionally long-polled.
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
 export const stateHelp = `pane state — show a session's metadata and event log
@@ -6,11 +6,24 @@ export const stateHelp = `pane state — show a session's metadata and event log
 Usage:
   pane state <session-id> [options]
 
-Non-blocking. Fetches session metadata (GET /v1/sessions/:id) plus the event
-log (GET /v1/sessions/:id/events) and prints them together.
+By default non-blocking: fetches session metadata (GET /v1/sessions/:id) plus
+the event log (GET /v1/sessions/:id/events) and prints them together.
+
+With --wait, blocks at the relay for up to <secs> if no new events are
+available since the cursor — returns as soon as something lands. Use this
+for headless polling agents that can't keep a WebSocket open (cron,
+FaaS, slow links): poll, then re-poll using next_cursor as --since on the
+next call. Compared to 'pane watch', it's higher latency per round-trip
+but no long-lived connection.
 
 Options:
-  --since <cursor>    Only return events after this opaque cursor.
+  --since <cursor>    Only return events after this opaque cursor. Pass
+                      next_cursor from the previous call to chain pages.
+  --wait <secs>       Long-poll window. The relay holds the request open
+                      for up to this many seconds, capped server-side at
+                      30. Without --since, this still returns immediately
+                      with whatever events exist — long-poll only blocks
+                      when there are NO new events to return.
   --url <url>         Relay base URL (overrides PANE_URL).
   --api-key <key>     Agent API key (overrides PANE_API_KEY).
   -h, --help          Show this help.
@@ -22,10 +35,26 @@ export async function runState(args) {
     if (!sessionId)
         fail("missing <session-id>", "invalid_args");
     const since = args.flags.get("since") ?? null;
+    // --wait <secs>: hand the server the long-poll window. The relay caps
+    // this at 30s; we pass the raw value and let the relay clamp (sending
+    // a higher number is not an error, just a clamp). 0 or unset means
+    // non-blocking — the default snapshot behaviour.
+    let waitSeconds;
+    const waitRaw = args.flags.get("wait");
+    if (waitRaw !== undefined) {
+        const n = Number(waitRaw);
+        if (!Number.isFinite(n) || n < 0) {
+            fail("--wait must be a non-negative number of seconds", "invalid_args");
+        }
+        waitSeconds = n;
+    }
     const client = makeClient(args);
     try {
         const meta = await client.getSession(sessionId);
-        const page = await client.getEvents(sessionId, { since });
+        const page = await client.getEvents(sessionId, {
+            since,
+            ...(waitSeconds !== undefined ? { waitSeconds } : {}),
+        });
         printJson({ meta, events: page.events, next_cursor: page.next_cursor });
     }
     catch (e) {

package/dist/commands/taste.js

@@ -37,16 +37,18 @@ Subcommands:
              { taste: string|null, updated_at: string|null, bytes: number }.
              taste is null and bytes is 0 when notes have never been written.
 
-  set        Whole-blob replace. Read markdown from stdin OR --file <path>
-             (exactly one). The relay rejects empty/whitespace-only payloads
-             and caps the blob at MAX_TASTE_BYTES (utf8). To clear the notes,
+  set        Whole-blob replace. Source the markdown via --file <path>,
+             --file - (read stdin), or by piping into 'pane taste set' with
+             no flag. The relay rejects empty/whitespace-only payloads and
+             caps the blob at MAX_TASTE_BYTES (utf8). To clear the notes,
              use 'pane taste clear', not 'set' with an empty body.
 
   clear      Delete the notes. Requires --yes (it is destructive). Prints
              { cleared: true }.
 
 Options:
-  --file <path>       Read 'set' input from <path> (otherwise reads stdin).
+  --file <path|->     Source for 'set' — a file path, or '-' to read stdin
+                      explicitly. Omit to fall back to piped stdin.
   --yes               Confirm 'clear'.
   --url <url>         Relay base URL (overrides PANE_URL).
   --api-key <key>     Agent API key (overrides PANE_API_KEY).
@@ -54,17 +56,17 @@ Options:
 
 Examples:
   pane taste get
-  echo "- denser layout\\n- no rounded corners" | pane taste set
   pane taste set --file ./taste.md
+  pane taste set --file -            # explicit stdin
+  echo "- denser layout" | pane taste set
   pane taste clear --yes
 
 Output: stdout is machine-readable JSON.`;
-// Drain process.stdin to a utf8 string. Resolves to "" when stdin is a TTY
-// (i.e. nothing was piped in), so the caller can detect "no input" and emit a
-// proper error instead of hanging forever waiting for keystrokes.
+// Drain process.stdin to a utf8 string. The caller is responsible for
+// deciding that stdin should be read (e.g. an explicit `--file -`, or a
+// non-TTY stdin where data is actually piped). In a TTY this would block
+// waiting for ^D, so the caller MUST gate on `process.stdin.isTTY` first.
 async function readStdin() {
-    if (process.stdin.isTTY)
-        return "";
     const chunks = [];
     for await (const chunk of process.stdin) {
         chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
@@ -83,15 +85,19 @@ async function runTasteGet(args) {
 }
 async function runTasteSet(args) {
     const filePath = args.flags.get("file");
-    const hasStdin = !process.stdin.isTTY;
-    if (filePath !== undefined && hasStdin) {
-        fail("'pane taste set' takes input from EITHER stdin OR --file <path>, not both", "invalid_args");
-    }
-    if (filePath === undefined && !hasStdin) {
-        fail("'pane taste set' needs input — pipe markdown on stdin or pass --file <path>", "invalid_args");
-    }
+    // Source the blob deterministically — no isTTY-flag fusing, because
+    // `!process.stdin.isTTY` is true under every non-interactive caller
+    // (pipes, redirects, closed fd, CI, agent harnesses) and would wrongly
+    // reject `--file` for the entire target audience. See issue #148.
+    //
+    //   --file -        → explicit stdin sentinel
+    //   --file <path>   → read that path (works in TTY and non-TTY alike)
+    //   (no --file)     → fall back to stdin IF non-TTY; error in a TTY
     let taste;
-    if (filePath !== undefined) {
+    if (filePath === "-") {
+        taste = await readStdin();
+    }
+    else if (filePath !== undefined) {
         try {
             taste = readFileSync(filePath, "utf8");
         }
@@ -99,9 +105,12 @@ async function runTasteSet(args) {
             fail(`failed to read --file '${filePath}': ${e instanceof Error ? e.message : String(e)}`, "invalid_args");
         }
     }
-    else {
+    else if (!process.stdin.isTTY) {
         taste = await readStdin();
     }
+    else {
+        fail("'pane taste set' needs input — pass --file <path>, pipe markdown on stdin, or use --file -", "invalid_args");
+    }
     if (taste.trim().length === 0) {
         fail("'pane taste set' refuses an empty or whitespace-only blob — use 'pane taste clear --yes' to delete the notes", "invalid_args");
     }

package/dist/commands/watch.js

@@ -7,6 +7,7 @@ import { openStream } from "@paneui/core";
 import { resolveConfig } from "../config.js";
 import { PaneClient } from "@paneui/core";
 import { printJsonLine, fail } from "../output.js";
+import { VERSION } from "../version.js";
 export const watchHelp = `pane watch — stream a session's events as JSON-lines
 
 Usage:
@@ -20,12 +21,30 @@ exits 0.
 Modes:
   (bare)              Run until SIGINT (Ctrl-C). Exit 0.
   --once              Exit 0 after the first event.
-  --type <t>          Exit 0 after the first event whose type equals <t>.
+  --type <t[,t2,…]>   Exit 0 after the first event whose type is in this
+                      comma-separated set. Without --filter-type, stdout
+                      still prints EVERY event until the match — --type
+                      controls the EXIT condition, --filter-type controls
+                      the OUTPUT.
 
 Options:
+  --filter-type <t[,t2,…]>
+                      Print only events whose type is in this set.
+                      system.* events (lifecycle: participant.joined,
+                      session.expired, …) and the terminal {"type":
+                      "_closed"} line always pass through, so the
+                      harness still sees them. Combine with --type X
+                      --filter-type X for "stream only X events and
+                      exit on the first one" — the literal-reading of
+                      --type alone that agents often expect.
   --since <cursor>    Replay only events after this opaque cursor.
-  --timeout <secs>    Fail with code ws_timeout if no frame (not even the
-                      replay-complete marker) arrives within this window.
+  --timeout <secs>    Wall-clock max wait. Fail with code ws_timeout if
+                      the natural exit condition (--once, --type, session
+                      close) doesn't happen within this many seconds.
+                      Frames arriving DO NOT reset the timer — this is
+                      the budget for "give up on the human", not an idle
+                      detector. Without --once or --type, bare watch
+                      will simply exit non-zero at the deadline.
   --url <url>         Relay base URL (overrides PANE_URL).
   --api-key <key>     Agent API key (overrides PANE_API_KEY).
   -h, --help          Show this help.
@@ -34,14 +53,52 @@ Each line is one event envelope: { id, session_id, author, ts, type, data,
 causation_id, idempotency_key }. The terminal line is {"type":"_closed"}.
 
 Pattern — Claude Code Monitor tool: run \`pane watch <id> --type form.submitted\`
-as a monitored process; the harness re-invokes the model when the line lands.`;
+as a monitored process; the harness re-invokes the model when the line lands.
+
+Wait for any of several events:
+  pane watch <id> --type form.submitted,form.cancelled --timeout 60
+
+Stream only matching events to stdout, exit on the first:
+  pane watch <id> --type form.submitted --filter-type form.submitted`;
+// Parse a comma-separated event-type list (e.g. "form.submitted,form.cancelled")
+// into a Set. Empty/whitespace entries are dropped. Returns null when the flag
+// wasn't given (so callers can distinguish "no filter" from "empty filter").
+// Exported for unit-test coverage; the wrapper around the actual openStream
+// integration is hard to test in isolation.
+export function parseTypeList(raw) {
+    if (raw === undefined)
+        return null;
+    const types = raw
+        .split(",")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    return new Set(types);
+}
+/**
+ * Decide whether `--filter-type` lets this event through to stdout. Lifecycle
+ * `system.*` events always pass — without that an agent waiting on
+ * `--filter-type form.submitted` would never see `system.participant.joined`
+ * and miss the "the human opened the URL" signal. Exported for testing.
+ */
+export function shouldPrintEvent(eventType, filterTypes) {
+    if (filterTypes === null)
+        return true;
+    if (eventType.startsWith("system."))
+        return true;
+    return filterTypes.has(eventType);
+}
 export async function runWatch(args) {
     const sessionId = args.positionals[0];
     if (!sessionId)
         fail("missing <session-id>", "invalid_args");
     const cfg = resolveConfig(args);
     const since = args.flags.get("since") ?? null;
-    const waitType = args.flags.get("type") ?? null;
+    // --type controls the EXIT condition (set of types that trigger exit 0
+    // on first match). --filter-type controls OUTPUT (the only event types
+    // printed to stdout; system.* and _closed always pass through). Each
+    // flag is independent — combine them only if you really want both.
+    const exitTypes = parseTypeList(args.flags.get("type"));
+    const filterTypes = parseTypeList(args.flags.get("filter-type"));
     const once = args.bools.has("once");
     let timeoutSec = null;
     const timeoutRaw = args.flags.get("timeout");
@@ -51,7 +108,11 @@ export async function runWatch(args) {
             fail("--timeout must be a positive number", "invalid_args");
         timeoutSec = t;
     }
-    const client = new PaneClient({ url: cfg.url, apiKey: cfg.apiKey });
+    const client = new PaneClient({
+        url: cfg.url,
+        apiKey: cfg.apiKey,
+        cliVersion: VERSION,
+    });
     let exited = false;
     const finish = (code) => {
         if (exited)
@@ -73,19 +134,20 @@ export async function runWatch(args) {
     // Track whether the relay told us the session expired before the socket
     // closed — a 1006/1008/1011 close after that is still a clean shutdown.
     let sawSessionExpired = false;
-    // Connection timeout: fail if no frame at all arrives within the window.
+    // Wall-clock timeout. The reporter's mental model (#137) and the skill
+    // text both treat this as "max wait until something happens" — i.e. an
+    // agent giving up on a human who never acts. The previous behaviour
+    // (clear the timer on first frame, never re-arm) made `--timeout`
+    // useless once any frame arrived, even a system.participant.joined
+    // emitted the moment a human connected. Frames now DO NOT reset the
+    // timer; the only ways `--timeout` doesn't fire are the natural exit
+    // conditions (--once, --type match, session close) finishing first.
     let timer;
     if (timeoutSec !== null) {
         timer = setTimeout(() => {
-            fail(`no stream frame within ${timeoutSec}s`, "ws_timeout");
+            fail(`no terminal condition met within ${timeoutSec}s`, "ws_timeout");
         }, timeoutSec * 1000);
     }
-    const sawFrame = () => {
-        if (timer) {
-            clearTimeout(timer);
-            timer = undefined;
-        }
-    };
     const handle = openStream({
         wsBaseUrl: client.wsBaseUrl,
         sessionId: sessionId,
@@ -93,11 +155,14 @@ export async function runWatch(args) {
         since,
     }, {
         onReplayComplete: () => {
-            sawFrame();
+            // No-op: replay-complete is informational, no timer interaction.
         },
         onEvent: (event) => {
-            sawFrame();
-            printJsonLine(event);
+            // Output filter: print only events the agent asked for. See
+            // shouldPrintEvent — system.* lifecycle events always pass.
+            if (shouldPrintEvent(event.type, filterTypes)) {
+                printJsonLine(event);
+            }
             // A system.session.expired event means the session is closing.
             if (event.type === "system.session.expired") {
                 sawSessionExpired = true;
@@ -108,7 +173,7 @@ export async function runWatch(args) {
                 finish(0);
                 return;
             }
-            if (waitType !== null && event.type === waitType) {
+            if (exitTypes !== null && exitTypes.has(event.type)) {
                 finish(0);
             }
         },

package/dist/config.js

@@ -3,6 +3,7 @@
 import { PaneClient } from "@paneui/core";
 import { fail } from "./output.js";
 import { readStore, storePath } from "./store.js";
+import { VERSION } from "./version.js";
 /**
  * Resolve url + apiKey and report the SOURCE of each, WITHOUT making a network
  * call and WITHOUT failing on a missing value (unlike `resolveConfig`). The
@@ -73,5 +74,25 @@ export function resolveConfig(args) {
 /** Build a PaneClient from resolved config. */
 export function makeClient(args) {
     const cfg = resolveConfig(args);
-    return new PaneClient({ url: cfg.url, apiKey: cfg.apiKey });
+    return new PaneClient({
+        url: cfg.url,
+        apiKey: cfg.apiKey,
+        // Sent as `x-pane-cli-version` on every relay request so the relay can
+        // return 426 cli_upgrade_required when this CLI is too old. Single
+        // source: ./version.ts.
+        cliVersion: VERSION,
+    });
+}
+/**
+ * Resolve just the relay URL — same precedence as `resolveConfig` but
+ * without insisting on an API key. For commands that hit unauthenticated
+ * relay routes (e.g. `pane skill` → GET /skills/pane/SKILL.md).
+ */
+export function resolveRelayUrl(args) {
+    const store = readStore();
+    const url = args.flags.get("url") ??
+        process.env.PANE_URL ??
+        store.url ??
+        DEFAULT_RELAY_URL;
+    return url.replace(/\/$/, "");
 }

package/dist/index.js

@@ -14,8 +14,12 @@ import { runConfig, configHelp } from "./commands/config.js";
 import { runLogout, logoutHelp } from "./commands/logout.js";
 import { runKeys, keysHelp } from "./commands/keys.js";
 import { runTaste, tasteHelp } from "./commands/taste.js";
+import { runFeedback, feedbackHelp } from "./commands/feedback.js";
 import { runDelete, deleteHelp } from "./commands/delete.js";
-const VERSION = "0.0.3";
+import { runSkill, skillHelp } from "./commands/skill.js";
+import { VERSION } from "./version.js";
+import { PaneApiError } from "@paneui/core";
+import { failUpgradeRequired } from "./output.js";
 const ROOT_HELP = `pane — a round-trip UI channel between agents and humans
 
 Usage:
@@ -27,7 +31,7 @@ Commands:
   create            Create a session (POST /v1/sessions). Prints session_id,
                     urls, tokens, expires_at.
   artifact          Manage reusable, versioned artifacts (create / version /
-                    update / search / list / show).
+                    update / search / list / show / delete).
   state <id>        Non-blocking snapshot: session metadata + event log.
   send <id>         Emit an agent event into a session.
   watch <id>        Stream a session's events as JSON-lines on stdout
@@ -38,8 +42,13 @@ Commands:
                     (get / set / clear) — presentation preferences the agent
                     has learned from human feedback and reads before
                     generating a pane artifact.
+  feedback          Submit / list one-shot feedback to the relay operator
+                    (create / list) — bug reports, feature requests, notes.
   config            Show the resolved relay config (no network call).
   logout            Clear the locally-saved relay URL + API key.
+  skill             Fetch the relay's SKILL.md to stdout, or just its
+                    version with 'pane skill version'. Used to install
+                    and keep the local skill copy in sync; no API key.
 
 Run \`pane <command> --help\` for command-specific options.
 
@@ -65,7 +74,14 @@ Output: stdout is machine-readable JSON; errors go to stderr as
 // handled from rawArgv[0] before parseArgs runs, so it never needs to be a
 // boolean flag — and keeping it out lets `pane create --version <n>` /
 // `pane artifact version` consume a value as a normal value-flag.
-const BOOLEAN_FLAGS = new Set(["json", "once", "help", "print-key", "yes"]);
+const BOOLEAN_FLAGS = new Set([
+    "json",
+    "once",
+    "help",
+    "print-key",
+    "yes",
+    "plain",
+]);
 async function main() {
     const rawArgv = process.argv.slice(2);
     // Version: handle before anything else.
@@ -105,8 +121,10 @@ async function main() {
         delete: deleteHelp,
         keys: keysHelp,
         taste: tasteHelp,
+        feedback: feedbackHelp,
         config: configHelp,
         logout: logoutHelp,
+        skill: skillHelp,
     };
     if (!(command in helps)) {
         process.stderr.write(JSON.stringify({
@@ -149,15 +167,30 @@ async function main() {
         case "taste":
             await runTaste(args);
             break;
+        case "feedback":
+            await runFeedback(args);
+            break;
         case "config":
             await runConfig(args);
             break;
         case "logout":
             await runLogout();
             break;
+        case "skill":
+            await runSkill(args);
+            break;
     }
 }
 main().catch((err) => {
+    // Funnel 426 cli_upgrade_required through the dedicated upgrade-message
+    // path so a command that throws raw (instead of going through
+    // failFromError) still produces the exact stderr block + exit 75 the
+    // SKILL.md tells the agent's harness to expect.
+    if (err instanceof PaneApiError &&
+        err.code === "cli_upgrade_required" &&
+        err.status === 426) {
+        failUpgradeRequired(err);
+    }
     process.stderr.write(JSON.stringify({
         error: {
             code: "internal",

package/dist/output.js

@@ -1,6 +1,8 @@
 // stdout/stderr helpers. The CLI is JSON-by-default: machine-readable on
 // stdout, human errors on stderr.
 import { PaneApiError } from "@paneui/core";
+import { fileURLToPath } from "node:url";
+import { detectInstallMethod, upgradeCommandFor, formatUpgradeMessage, EXIT_CLI_UPGRADE_REQUIRED, } from "./upgrade.js";
 /** Print a value as pretty JSON to stdout. */
 export function printJson(value) {
     process.stdout.write(JSON.stringify(value, null, 2) + "\n");
@@ -29,6 +31,16 @@ export function fail(message, code = "error", details, extra) {
 }
 /** Translate a thrown error (incl. PaneApiError) into a fail() exit. */
 export function failFromError(err) {
+    // 426 cli_upgrade_required gets its own dedicated exit path: a
+    // human-readable upgrade message on stderr and a stable exit code
+    // (sysexits EX_TEMPFAIL = 75) that the SKILL.md instructs the agent's
+    // harness to branch on. Everything else falls through to the generic
+    // JSON envelope below.
+    if (err instanceof PaneApiError &&
+        err.code === "cli_upgrade_required" &&
+        err.status === 426) {
+        failUpgradeRequired(err);
+    }
     if (err instanceof PaneApiError) {
         fail(err.message, err.code, err.details, {
             hint: err.hint,
@@ -38,3 +50,28 @@ export function failFromError(err) {
     }
     fail(err instanceof Error ? err.message : String(err), "internal");
 }
+/**
+ * Print the upgrade message to stderr and exit 75. Pulled out of
+ * failFromError so the top-level main().catch can also funnel through it
+ * — the two entry points must produce identical output for the SKILL.md's
+ * "if you see exit 75…" instructions to be reliable.
+ *
+ * The install-method detection reads `import.meta.url` of the CLI entry,
+ * resolved from the call site that imports this module. Inlining the
+ * resolution here keeps each command's own error-handling free of the
+ * detail.
+ */
+export function failUpgradeRequired(err) {
+    // The CLI entry is packages/cli/dist/index.js (after build) or
+    // packages/cli/src/index.ts (when running from source via tsx). Either
+    // way, the detector only looks at the path's shape, so resolving from
+    // *this* file works — output.ts sits alongside index.ts/index.js in
+    // both layouts.
+    const entryPath = fileURLToPath(import.meta.url);
+    const method = detectInstallMethod(entryPath);
+    const details = (err.details ?? {});
+    const minVersion = typeof details.min_version === "string" ? details.min_version : "0.0.0";
+    const command = upgradeCommandFor(method, minVersion);
+    process.stderr.write(formatUpgradeMessage(err, method, command) + "\n");
+    process.exit(EXIT_CLI_UPGRADE_REQUIRED);
+}

package/dist/upgrade.js

@@ -0,0 +1,115 @@
+// CLI auto-upgrade helpers — install-method detection and message formatting.
+//
+// Called by the top-level error handler when a relay returns 426
+// `cli_upgrade_required`. The goal is to print a single, machine-parseable
+// line the agent can lift verbatim — and tell the human (or the agent's
+// harness) exactly what to run instead of a generic "upgrade @paneui/cli".
+//
+// Detection is best-effort: we inspect `process.execPath` and the CLI's own
+// install path. There's no programmatic "ask npm what installed me" API, so
+// the heuristics below are matched against the well-known install layouts
+// of each package manager. Anything unrecognized lands in `unknown`, which
+// means "tell the agent to ask the human" rather than guess.
+/**
+ * Detection rules, ordered most-specific to least. Each rule looks at the
+ * directory the CLI is running from — caller passes `import.meta.url`-
+ * derived absolute path for the CLI entry. The actual file at that path
+ * doesn't need to exist; we're only pattern-matching the path itself, so
+ * tests can pass synthetic strings.
+ *
+ * Patterns are deliberately loose (substring tests, not exact prefixes) so
+ * the same rule handles per-user installs (`~/.npm-global/lib/node_modules/`),
+ * system installs (`/usr/lib/node_modules/`), and the macOS/Linux
+ * variations within each manager — without listing every layout.
+ */
+export function detectInstallMethod(entryPath) {
+    // Volta wraps every binary in a shim under ~/.volta/tools/image/packages/
+    // and re-exports it via ~/.volta/bin/. Either path is a positive match.
+    if (entryPath.includes("/.volta/"))
+        return "volta";
+    // Bun's global registry: ~/.bun/install/global/node_modules/@paneui/cli/...
+    if (entryPath.includes("/.bun/install/global/"))
+        return "bun-global";
+    // npm global, in both common shapes:
+    //   /usr/(local/)?lib/node_modules/@paneui/cli/...  (system)
+    //   ~/.npm-global/lib/node_modules/@paneui/cli/...   (npm prefix)
+    //   ~/.nvm/versions/node/vXX/lib/node_modules/...    (nvm)
+    if (/\/lib\/node_modules\/@paneui\/cli\//.test(entryPath) ||
+        /\/lib\/node_modules\/\.bin\//.test(entryPath)) {
+        return "npm-global";
+    }
+    // npx caches the package under ~/Library/Caches/_npx (macOS) or
+    // ~/.npm/_npx (Linux) and runs it from a node_modules inside that dir.
+    // Surface this distinctly from a real vendored install: with an npx
+    // execution there is no project package.json owning the version and no
+    // global to upgrade — the user runs `npx @paneui/cli@<version>` each
+    // time, so the right answer is "ask the human / re-run with a newer
+    // explicit version".
+    if (entryPath.includes("/_npx/"))
+        return "unknown";
+    // Vendored: the CLI lives inside the *project's* node_modules — i.e. the
+    // user did `npm i @paneui/cli` (no -g) and runs it via a local script.
+    // We can't safely upgrade this for them; package.json owns it.
+    if (entryPath.includes("/node_modules/@paneui/cli/"))
+        return "vendored";
+    // pnpm temp, asdf, or anything else.
+    return "unknown";
+}
+/**
+ * Returns the shell command the human (or the agent, in a sandbox it owns)
+ * can run to upgrade @paneui/cli to satisfy `minVersion`. `null` means "no
+ * portable command exists — escalate to the human."
+ *
+ * Always pin the upgrade target to `>=${minVersion}` instead of `@latest`
+ * so a self-hosted relay that requires 0.0.7 doesn't drag the client to a
+ * future 0.1.0 that may have its own incompatibilities. The trailing
+ * `@latest`-equivalent is fine for the operator who deliberately
+ * fast-forwards.
+ */
+export function upgradeCommandFor(method, minVersion) {
+    const spec = `@paneui/cli@>=${minVersion}`;
+    switch (method) {
+        case "npm-global":
+            return `npm install -g ${spec}`;
+        case "bun-global":
+            return `bun install -g ${spec}`;
+        case "volta":
+            return `volta install ${spec}`;
+        case "vendored":
+        case "unknown":
+            return null;
+    }
+}
+/**
+ * The deterministic stderr block the CLI prints on a 426 response. The agent
+ * is expected to read this verbatim and (per SKILL.md) run the printed
+ * command, then re-run its original `pane` invocation once. Format is held
+ * stable across CLI versions so the skill's instructions don't drift — a
+ * change here is a contract change.
+ */
+export function formatUpgradeMessage(err, method, command) {
+    // The relay's 426 payload puts the two version strings under details. We
+    // tolerate a missing/malformed details object so a misbehaving relay
+    // can't crash the CLI's own error path — show whatever we have.
+    const details = (err.details ?? {});
+    const minVersion = typeof details.min_version === "string" ? details.min_version : "?";
+    const yourVersion = typeof details.your_version === "string" ? details.your_version : "?";
+    const lines = [];
+    lines.push(`pane: this relay requires @paneui/cli >= ${minVersion} (you have ${yourVersion}).`);
+    if (command !== null) {
+        lines.push(`To upgrade: ${command}`);
+    }
+    else if (method === "vendored") {
+        lines.push("Install method: vendored (inside a project's node_modules). Bump the @paneui/cli version in that project's package.json and re-install — the CLI isn't safe to upgrade globally for a vendored install.");
+    }
+    else {
+        lines.push("Install method: unknown. Ask the human to upgrade @paneui/cli — the install path didn't match any pattern we recognize (npm-global, bun-global, volta).");
+    }
+    return lines.join("\n");
+}
+/**
+ * Stable exit code used by the CLI on a `cli_upgrade_required` response.
+ * Sysexits.h's `EX_TEMPFAIL` — "temporary failure; retry after fixing".
+ * Documented in SKILL.md so an agent's harness can branch on it.
+ */
+export const EXIT_CLI_UPGRADE_REQUIRED = 75;

package/dist/version.js

@@ -0,0 +1,11 @@
+// Single source of truth for the CLI version string.
+//
+// - `pane --version` prints this verbatim.
+// - Every PaneClient construction passes it as `cliVersion`, which surfaces
+//   as the `x-pane-cli-version` header on every relay request — drives the
+//   relay's version-skew check (HTTP 426 `cli_upgrade_required`).
+//
+// Keep this in lockstep with packages/cli/package.json's `version` field;
+// they're consulted in different places (here for the runtime header,
+// package.json for npm publish + dependency resolution).
+export const VERSION = "0.0.5";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paneui/cli",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Command-line client for the Pane relay: create sessions, inspect state, send and watch events.",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,7 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@paneui/core": "^0.0.3"
+    "@paneui/core": "^0.0.5"
   },
   "devDependencies": {
     "@types/node": "^22.7.0",