@pinchpass/cli 1.1.1 → 1.2.0

package/dist/index.js

@@ -1,126 +1,64 @@
+import * as piCodingAgent from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { StringEnum } from "@earendil-works/pi-ai";
-import { Box, Text } from "@earendil-works/pi-tui";
+import { CURSOR_MARKER, Key, Text, matchesKey, renderFakeCursor, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
 import { spawn } from "node:child_process";
-import { accessSync, constants, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { resolve } from "node:path";
+import { buildArgs, chooseVia } from "./args.js";
+import { BINARY_MISSING, findBinary, updateNotice } from "./binary.js";
+import { writeEnvKey } from "./env.js";
+import { takeJsonBlobs } from "./json-stream.js";
 /** Small figlet "small" font rendering of PINCHPASS. */
 const PINCHPASS_ART = "  ___ ___ _  _  ___ _  _ ___  _   ___ ___ \n" +
     " | _ \\_ _| \\| |/ __| || | _ \\/_\\ / __/ __|\n" +
     " |  _/| || .` | (__| __ |  _/ _ \\\\__ \\__ \\\n" +
     " |_| |___|_|\\_|\\___|_||_|_|/_/ \\_\\___/___/";
-/** Extra directories where the postinstall script may have placed the binary. */
-const FALLBACK_DIRS = [
-    join(homedir(), ".local", "bin"),
-    join(homedir(), ".openclaw", "bin"),
-    join(homedir(), ".pi", "bin"),
-];
-function findBinary() {
-    const name = process.platform === "win32" ? "pinchpass.exe" : "pinchpass";
-    const sep = process.platform === "win32" ? ";" : ":";
-    const dirs = [...(process.env.PATH ?? "").split(sep).filter(Boolean), ...FALLBACK_DIRS];
-    for (const dir of dirs) {
-        try {
-            const candidate = join(dir, name);
-            accessSync(candidate, constants.X_OK);
-            return candidate;
-        }
-        catch {
-            // keep looking
-        }
-    }
-    return null;
-}
-const BINARY_MISSING = `The pinchpass binary is not installed. Install it with one of:
-
-  npm i -g @pinchpass/cli      # downloads the prebuilt binary for your platform
-  go install github.com/rubybear-lgtm/pinchpass@latest
-
-Then try request_secret again.`;
-/** Pull complete JSON objects out of a (possibly pretty-printed) stream. */
-function takeJsonBlobs(text) {
-    const blobs = [];
-    let depth = 0;
-    let start = -1;
-    let inString = false;
-    let escaped = false;
-    for (let i = 0; i < text.length; i++) {
-        const c = text[i];
-        if (inString) {
-            if (escaped)
-                escaped = false;
-            else if (c === "\\")
-                escaped = true;
-            else if (c === '"')
-                inString = false;
-            continue;
-        }
-        if (c === '"') {
-            inString = true;
-            continue;
-        }
-        if (c === "{") {
-            if (depth === 0)
-                start = i;
-            depth++;
-        }
-        else if (c === "}") {
-            depth--;
-            if (depth === 0 && start >= 0) {
-                try {
-                    blobs.push(JSON.parse(text.slice(start, i + 1)));
-                }
-                catch {
-                    // skip malformed output
-                }
-                start = -1;
-            }
-        }
-    }
-    return { blobs, rest: start >= 0 ? text.slice(start) : "" };
+const RESULT_SCHEMA = Type.Object({
+    success: Type.Boolean(),
+    aborted: Type.Boolean(),
+    via: StringEnum(["modal", "link"]),
+    names: Type.Array(Type.String()),
+    saved: Type.Array(Type.String()),
+    out: Type.Optional(Type.String()),
+    url: Type.Optional(Type.String()),
+    port: Type.Optional(Type.Number()),
+    message: Type.Optional(Type.String()),
+    error: Type.Optional(Type.String()),
+});
+function makeResult(details, text, isError = false) {
+    return {
+        content: [{ type: "text", text }],
+        details,
+        structuredContent: { ...details },
+        isError,
+    };
 }
-/** Shell-escape a value for a double-quoted .env line (mirrors store.go). */
-function escapeEnvValue(s) {
-    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$").replace(/`/g, "\\`");
-}
-/** Write/update a single KEY="value" line in a .env file (mirrors store.go). */
-function writeEnvKey(path, key, value) {
-    mkdirSync(dirname(path), { recursive: true });
-    const line = `${key}="${escapeEnvValue(value)}"`;
-    let existing = "";
-    try {
-        existing = readFileSync(path, "utf8");
-    }
-    catch {
-        // new file
-    }
-    const out = [];
-    let replaced = false;
-    for (const l of existing.split("\n")) {
-        const t = l.trim();
-        if (t === "")
-            continue;
-        if (t.startsWith(key + "=")) {
-            out.push(line);
-            replaced = true;
-        }
-        else {
-            out.push(l);
-        }
-    }
-    if (!replaced)
-        out.push(line);
-    writeFileSync(path, out.join("\n") + "\n", { mode: 0o600 });
+const localFileQueues = new Map();
+/** Fallback used when the host does not expose `withFileMutationQueue`. */
+function localFileQueue(filePath, fn) {
+    const key = resolve(filePath);
+    const previous = localFileQueues.get(key) ?? Promise.resolve();
+    const run = previous.then(fn, fn);
+    localFileQueues.set(key, run.catch(() => undefined));
+    return run;
 }
+const withFileQueue = typeof piCodingAgent.withFileMutationQueue === "function"
+    ? piCodingAgent.withFileMutationQueue
+    : localFileQueue;
 /**
  * Branded masked secret dialog (Pi TUI overlay). The value is rendered as
- * bullets, never echoed, and submitted straight to the caller.
+ * bullets, never echoed, and submitted straight to the caller. Handles
+ * bracketed paste and terminal escape sequences explicitly.
  */
 async function promptSecretTUI(ctx, name, note, signal) {
-    return ctx.ui.custom((tui, theme, _kb, done) => {
+    return ctx.ui.custom((tui, theme, kb, done) => {
         let value = "";
         let alive = true;
+        let pasteBuffer = "";
+        let isInPaste = false;
+        let cachedLines;
+        let cachedWidth = 0;
+        let cachedValueLength = -1;
         const finish = (v) => {
             if (!alive)
                 return;
@@ -131,71 +69,116 @@ async function promptSecretTUI(ctx, name, note, signal) {
         };
         const onAbort = () => finish(undefined);
         if (signal) {
-            if (signal.aborted) {
+            if (signal.aborted)
                 onAbort();
-            }
-            else {
+            else
                 signal.addEventListener("abort", onAbort, { once: true });
-            }
         }
+        const refresh = () => {
+            cachedLines = undefined;
+            tui.requestRender(true);
+        };
         const comp = {
             focused: true,
             handleInput(data) {
                 if (!alive)
                     return;
-                // Ignore escape sequences (arrows etc.) as a whole chunk.
-                if (data.startsWith("\u001b["))
+                // Bracketed paste: accumulate until the end marker, then insert.
+                if (data.includes("\u001b[200~")) {
+                    isInPaste = true;
+                    pasteBuffer = "";
+                    data = data.replace("\u001b[200~", "");
+                }
+                if (isInPaste) {
+                    pasteBuffer += data;
+                    const end = pasteBuffer.indexOf("\u001b[201~");
+                    if (end === -1) {
+                        refresh();
+                        return;
+                    }
+                    const pasted = pasteBuffer.slice(0, end);
+                    const remaining = pasteBuffer.slice(end + 6);
+                    pasteBuffer = "";
+                    isInPaste = false;
+                    for (const ch of pasted) {
+                        if (ch >= " " && ch !== "\u007f")
+                            value += ch;
+                    }
+                    if (remaining)
+                        comp.handleInput?.(remaining);
+                    else
+                        refresh();
                     return;
-                if (data === "\u001b") {
+                }
+                if (kb.matches(data, "tui.select.cancel") || matchesKey(data, Key.escape)) {
                     finish(undefined);
                     return;
                 }
+                if (kb.matches(data, "tui.input.submit") || matchesKey(data, Key.enter) || data === "\n") {
+                    finish(value);
+                    return;
+                }
+                if (matchesKey(data, Key.backspace) || matchesKey(data, Key.delete)) {
+                    value = value.slice(0, -1);
+                    refresh();
+                    return;
+                }
+                // Ignore unhandled escape sequences (arrows, home/end, …) as a chunk.
+                if (data.startsWith("\u001b")) {
+                    refresh();
+                    return;
+                }
                 for (const ch of data) {
-                    if (ch === "\r" || ch === "\n") {
-                        finish(value);
-                        return;
-                    }
-                    if (ch === "\u0003") {
-                        finish(undefined);
-                        return;
-                    }
-                    if (ch === "\u007f" || ch === "\b") {
-                        value = value.slice(0, -1);
-                    }
-                    else if (ch >= " " && ch !== "\u007f") {
+                    if (ch >= " " && ch !== "\u007f")
                         value += ch;
-                    }
                 }
-                tui.requestRender(true);
+                refresh();
+            },
+            invalidate() {
+                cachedLines = undefined;
             },
-            invalidate() { },
             render(width) {
+                if (cachedLines && cachedWidth === width && cachedValueLength === value.length)
+                    return cachedLines;
+                const renderWidth = Math.max(1, width);
                 const art = PINCHPASS_ART.split("\n");
-                const boxW = Math.min(width - 6, 46);
-                const pad = Math.max(0, Math.floor((width - boxW) / 2));
+                const artWidth = art.reduce((max, line) => Math.max(max, visibleWidth(line)), 0);
+                const boxWidth = Math.min(Math.max(artWidth + 4, 40), Math.max(20, renderWidth - 2));
+                const innerWidth = Math.max(4, boxWidth - 4);
+                const leftPad = " ".repeat(Math.max(0, Math.floor((renderWidth - boxWidth) / 2)));
+                const border = (s) => theme.fg("borderAccent", s);
+                const boxed = (content) => {
+                    const clipped = truncateToWidth(content, innerWidth, "");
+                    const fill = " ".repeat(Math.max(0, innerWidth - visibleWidth(clipped)));
+                    return `${leftPad}${border("│")} ${clipped}${fill} ${border("│")}`;
+                };
+                const centered = (raw) => {
+                    const w = visibleWidth(raw);
+                    if (w >= innerWidth)
+                        return raw;
+                    const left = Math.floor((innerWidth - w) / 2);
+                    return " ".repeat(left) + raw + " ".repeat(innerWidth - w - left);
+                };
                 const lines = [];
                 lines.push("");
-                for (const a of art) {
-                    lines.push(" ".repeat(pad) + theme.fg("muted", a));
-                }
-                lines.push(" ".repeat(pad) + theme.fg("toolTitle", theme.bold(`  🔐  ${name}`)));
+                lines.push(`${leftPad}${border(`╭${"─".repeat(Math.max(0, boxWidth - 2))}╮`)}`);
+                for (const a of art)
+                    lines.push(boxed(centered(theme.fg("muted", a))));
+                lines.push(boxed(""));
+                lines.push(boxed(theme.fg("toolTitle", theme.bold(`  🔐  ${name}`))));
                 if (note)
-                    lines.push(" ".repeat(pad) + theme.fg("dim", `      ${note}`));
-                lines.push("");
-                const dots = Math.min(value.length, boxW - 8);
-                const mask = "•".repeat(dots);
-                const cursor = value.length < boxW - 8 ? "█" : "";
-                const inner = "  " + mask + cursor + " ".repeat(Math.max(0, boxW - 4 - dots - (cursor ? 1 : 0)));
-                lines.push(" ".repeat(pad) + theme.fg("borderAccent", "┌" + "─".repeat(boxW - 2) + "┐"));
-                lines.push(" ".repeat(pad) +
-                    theme.fg("borderAccent", "│") +
-                    theme.fg("accent", inner) +
-                    theme.fg("borderAccent", "│"));
-                lines.push(" ".repeat(pad) + theme.fg("borderAccent", "└" + "─".repeat(boxW - 2) + "┘"));
+                    lines.push(boxed(theme.fg("dim", `      ${note}`)));
+                lines.push(boxed(""));
+                const maxDots = Math.max(1, innerWidth - 3);
+                const dots = "•".repeat(Math.min(value.length, maxDots));
+                const cursor = `${CURSOR_MARKER}${renderFakeCursor(theme.fg("accent", " "))}`;
+                lines.push(boxed(`  ${theme.fg("accent", dots)}${cursor}`));
+                lines.push(`${leftPad}${border(`╰${"─".repeat(Math.max(0, boxWidth - 2))}╯`)}`);
+                lines.push(boxed(`${theme.fg("dim", "enter submit")}${theme.fg("muted", "    esc cancel")}`));
                 lines.push("");
-                lines.push(" ".repeat(pad) +
-                    theme.fg("dim", "enter submit") +
-                    theme.fg("muted", "    esc cancel"));
+                cachedLines = lines;
+                cachedWidth = width;
+                cachedValueLength = value.length;
                 return lines;
             },
         };
@@ -205,71 +188,64 @@ async function promptSecretTUI(ctx, name, note, signal) {
         overlayOptions: { width: "60%", minWidth: 54, maxHeight: "65%" },
     });
 }
+/** Open a URL in the user's browser (best effort; loopback links only). */
+function openInBrowser(url) {
+    if (process.platform === "darwin") {
+        const p = spawn("open", [url], { stdio: "ignore", detached: true });
+        p.on("error", () => { });
+        p.unref();
+    }
+    else if (process.platform === "win32") {
+        const p = spawn("cmd", ["/c", "start", "", url], { stdio: "ignore", detached: true });
+        p.on("error", () => { });
+        p.unref();
+    }
+    else {
+        const p = spawn("xdg-open", [url], { stdio: "ignore", detached: true });
+        p.on("error", () => { });
+        p.unref();
+    }
+}
+/** Auto-open a link only when it is reachable from this machine. */
+function maybeOpenBrowser(url, mode) {
+    if (mode !== "tui")
+        return;
+    if (process.env.PINCHPASS_NO_OPEN)
+        return;
+    if (!/^http:\/\/(127\.0\.0\.1|localhost|\[::1\]):/.test(url))
+        return;
+    try {
+        openInBrowser(url);
+    }
+    catch {
+        // best effort — the link is still rendered in the TUI
+    }
+}
 /**
- * Collect secrets directly in the Pi UI via modal dialogs. The value goes
- * straight from the user's keyboard into the .env file — it is never sent to
- * the LLM, never enters the session transcript, and no server is started.
+ * Collect secrets directly in the Pi TUI via masked modal dialogs. Each value
+ * goes straight from the user's keyboard into the .env file — it is never sent
+ * to the LLM, never enters the session transcript, and no server is started.
  */
 async function collectViaModal(ctx, params, signal) {
     const outPath = resolve(ctx.cwd, params.out ?? ".env");
+    const ignored = [];
+    if (typeof params.ttl === "number")
+        ignored.push("ttl (link mode only)");
+    const ignoreNote = ignored.length ? ` (ignored in modal mode: ${ignored.join(", ")})` : "";
     const saved = [];
     for (const name of params.names) {
-        const value = ctx.mode === "tui"
-            ? await promptSecretTUI(ctx, name, params.note ?? "", signal)
-            : await ctx.ui.input(`Enter ${name}`, params.note ?? `Secret value for ${name}`, {
-                signal,
-            });
+        const value = await promptSecretTUI(ctx, name, params.note ?? "", signal);
         if (value === undefined) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Secret request cancelled — ${name} not provided.${saved.length ? ` (${saved.join(", ")} already saved)` : ""} No further secrets were collected.`,
-                    },
-                ],
-                details: { success: false, names: params.names, saved, aborted: true },
-            };
+            return makeResult({ success: false, aborted: true, via: "modal", names: params.names, saved, out: outPath, error: "cancelled" }, `Secret request cancelled — ${name} not provided.${saved.length ? ` (${saved.join(", ")} already saved)` : ""} No further secrets were collected.`);
         }
         const trimmed = value.trim();
         if (!trimmed) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Secret request cancelled — ${name} was empty.${saved.length ? ` (${saved.join(", ")} already saved)` : ""}`,
-                    },
-                ],
-                details: { success: false, names: params.names, saved, aborted: true },
-            };
+            return makeResult({ success: false, aborted: true, via: "modal", names: params.names, saved, out: outPath, error: "empty" }, `Secret request cancelled — ${name} was empty.${saved.length ? ` (${saved.join(", ")} already saved)` : ""}`);
         }
-        writeEnvKey(outPath, name, trimmed);
+        await withFileQueue(outPath, async () => writeEnvKey(outPath, name, trimmed));
         saved.push(name);
     }
-    return {
-        content: [
-            { type: "text", text: `✅ Secrets collected via Pi modal: ${saved.join(", ")}\nSaved to ${outPath}` },
-        ],
-        details: {
-            success: true,
-            names: saved,
-            message: "Secrets collected via Pi modal.",
-            url: undefined,
-            out: outPath,
-            aborted: false,
-        },
-    };
-}
-function buildArgs(params) {
-    const args = ["request", ...params.names, "-json"];
-    if (params.tunnel)
-        args.push("-tunnel");
-    if (params.note)
-        args.push("-note", params.note);
-    if (typeof params.ttl === "number")
-        args.push("-ttl", String(params.ttl));
-    if (params.out)
-        args.push("-out", params.out);
-    return args;
+    return makeResult({ success: true, aborted: false, via: "modal", names: params.names, saved, out: outPath }, `✅ Secrets collected via Pi modal: ${saved.join(", ")}\nSaved to ${outPath}${ignoreNote}`);
 }
 /* ------------------------------------------------------------------ */
 /* Pi native tool                                                      */
@@ -286,7 +262,7 @@ function registerPiTool(pi) {
         promptGuidelines: [
             "Use request_secret when you need an API key, token, or password from the user — never ask them to paste secrets directly into chat.",
             "request_secret streams the link (or shows the modal) to the user immediately; wait for its result before continuing.",
-            "Use request_secret with tunnel: true when the user is not on the same machine as this agent.",
+            "Use request_secret with tunnel: true when the user is not on the same machine as this agent — tunnel always uses the encrypted browser link, never the modal.",
             "Use request_secret with via: 'link' to force the encrypted browser link, or via: 'modal' to force the Pi dialog.",
         ],
         parameters: Type.Object({
@@ -302,31 +278,44 @@ function registerPiTool(pi) {
                 description: "How to collect: 'modal' prompts in the Pi UI, 'link' generates the encrypted browser link, 'auto' picks modal in the TUI and link elsewhere (default: auto)",
             })),
         }),
+        outputSchema: RESULT_SCHEMA,
+        executionMode: "sequential",
         async execute(_toolCallId, params, signal, onUpdate, ctx) {
-            const via = params.via ?? "auto";
-            const useModal = via === "modal" || (via === "auto" && ctx.mode === "tui");
+            const { via, downgraded } = chooseVia(params.via, params.tunnel, ctx.mode);
+            const useModal = via === "modal";
+            if (useModal && !ctx.hasUI) {
+                return makeResult({
+                    success: false,
+                    aborted: false,
+                    via: "modal",
+                    names: params.names,
+                    saved: [],
+                    error: "no-ui",
+                }, "Modal collection is unavailable here (no interactive UI in this mode). Call request_secret again with via: 'link' to use the encrypted browser link.", true);
+            }
             if (useModal) {
-                if (!ctx.hasUI) {
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: "Modal collection is unavailable here (no interactive UI in this mode). Call request_secret again with via: 'link' to use the encrypted browser link.",
-                            },
-                        ],
-                        details: { success: false, names: params.names, error: "no-ui" },
-                    };
-                }
                 return collectViaModal(ctx, params, signal);
             }
+            const downgradeNote = downgraded
+                ? " (modal needs the interactive TUI; used the encrypted browser link instead)"
+                : "";
             const binary = findBinary();
             if (!binary) {
-                throw new Error(BINARY_MISSING);
+                return makeResult({
+                    success: false,
+                    aborted: false,
+                    via: "link",
+                    names: params.names,
+                    saved: [],
+                    error: "binary-missing",
+                    message: "pinchpass binary not found",
+                }, BINARY_MISSING, true);
             }
             const child = spawn(binary, buildArgs(params), {
                 cwd: ctx.cwd,
                 stdio: ["ignore", "pipe", "pipe"],
             });
+            const notice = updateNotice(binary);
             let buffer = "";
             let stderr = "";
             const blobs = [];
@@ -358,8 +347,18 @@ function registerPiTool(pi) {
                                             text: `🔗 One-time E2E-encrypted secret request link${ttlNote}:\n${b.url}\n\nAsk the user to open it and submit ${(b.names ?? []).join(", ") || "the secret"}.`,
                                         },
                                     ],
-                                    details: { url: b.url, port: b.port, names: b.names ?? [] },
+                                    details: { url: b.url, port: b.port, names: b.names ?? [], via: "link" },
                                 });
+                                if (ctx.mode === "tui") {
+                                    const widget = [
+                                        `🔗 pinchpass — open this link to submit ${(b.names ?? []).join(", ") || "the secret"}:`,
+                                        b.url,
+                                    ];
+                                    if (notice)
+                                        widget.push(`⚠ ${notice}`);
+                                    ctx.ui.setWidget("pinchpass-link", widget);
+                                }
+                                maybeOpenBrowser(b.url, ctx.mode);
                             }
                         }
                     });
@@ -369,49 +368,96 @@ function registerPiTool(pi) {
                     child.on("error", (err) => reject(err));
                     child.on("close", (code) => resolve(code));
                 });
-                if (signal?.aborted) {
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: `Secret request cancelled (${params.names.join(", ")}). No value was saved.`,
-                            },
-                        ],
-                        details: { success: false, names: params.names, aborted: true },
-                    };
-                }
+                const out = resolve(ctx.cwd, params.out ?? ".env");
                 const firstBlob = blobs[0];
                 const lastBlob = blobs[blobs.length - 1];
+                // The CLI prints blob 1 before waiting and blob 2 after. A hard failure
+                // (decrypt/save error) exits non-zero with only blob 1, so a single
+                // blob is never a completed request.
+                const completed = exitCode === 0 && blobs.length > 1 && lastBlob?.success === true;
+                if (signal?.aborted) {
+                    if (completed) {
+                        const names = lastBlob.names ?? params.names;
+                        return makeResult({
+                            success: true,
+                            aborted: false,
+                            via: "link",
+                            names,
+                            saved: names,
+                            out,
+                            url: firstBlob?.url,
+                            message: lastBlob.message,
+                            port: lastBlob.port,
+                        }, `✅ Secrets collected: ${names.join(", ")}\nSaved to ${params.out ?? ".env"} in ${ctx.cwd}`);
+                    }
+                    return makeResult({
+                        success: false,
+                        aborted: true,
+                        via: "link",
+                        names: params.names,
+                        saved: [],
+                        error: "cancelled",
+                    }, `Secret request cancelled (${params.names.join(", ")}). No value was saved.`);
+                }
                 if (!lastBlob) {
-                    throw new Error(`pinchpass exited without JSON output (code ${exitCode}).${stderr ? `\n${stderr}` : ""}`);
+                    return makeResult({
+                        success: false,
+                        aborted: false,
+                        via: "link",
+                        names: params.names,
+                        saved: [],
+                        error: "no-output",
+                        message: `pinchpass exited without JSON output (code ${exitCode})`,
+                    }, `pinchpass exited without JSON output (code ${exitCode}).${stderr ? `\n${stderr}` : ""}`, true);
                 }
-                const success = lastBlob.success === true;
-                const lines = success
-                    ? [`✅ Secrets collected: ${(lastBlob.names ?? params.names).join(", ")}`]
-                    : [`❌ ${lastBlob.message ?? "Secret request failed."}`];
+                const names = lastBlob.names ?? params.names;
+                const failureMessage = exitCode !== 0
+                    ? stderr.trim() || `pinchpass exited with code ${exitCode}`
+                    : lastBlob.message ?? "Secret request failed.";
+                const lines = completed
+                    ? [`✅ Secrets collected: ${names.join(", ")}`]
+                    : [`❌ ${failureMessage}`];
                 if (firstBlob?.url)
                     lines.push(`Link: ${firstBlob.url}`);
-                if (success)
+                if (completed)
                     lines.push(`Saved to ${params.out ?? ".env"} in ${ctx.cwd}`);
-                return {
-                    content: [{ type: "text", text: lines.join("\n") }],
-                    details: {
-                        success,
-                        names: lastBlob.names ?? params.names,
-                        url: firstBlob?.url,
-                        message: lastBlob.message,
-                        port: lastBlob.port,
-                        out: resolve(ctx.cwd, params.out ?? ".env"),
-                        aborted: false,
-                    },
-                };
+                if (downgradeNote)
+                    lines.push(downgradeNote.trim());
+                if (notice)
+                    lines.push(`⚠ ${notice}`);
+                return makeResult({
+                    success: completed,
+                    aborted: false,
+                    via: "link",
+                    names,
+                    saved: completed ? names : [],
+                    url: firstBlob?.url,
+                    message: completed ? lastBlob.message : failureMessage,
+                    port: lastBlob.port,
+                    out,
+                    error: completed ? undefined : exitCode !== 0 ? "cli-failed" : "not-provisioned",
+                }, lines.join("\n"), !completed);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return makeResult({
+                    success: false,
+                    aborted: false,
+                    via: "link",
+                    names: params.names,
+                    saved: [],
+                    error: "spawn-failed",
+                    message,
+                }, `Failed to start pinchpass: ${message}${stderr ? `\n${stderr}` : ""}`, true);
             }
             finally {
                 if (signal)
                     signal.removeEventListener("abort", onAbort);
+                if (ctx.mode === "tui")
+                    ctx.ui.setWidget("pinchpass-link", undefined);
             }
         },
-        /* Pretty TUI rendering: call line, result card. */
+        /* Pretty TUI rendering: call line, result card (default tool shell). */
         renderCall(args, theme) {
             const names = (args.names ?? []).join(", ");
             const via = args.via ?? "auto";
@@ -425,38 +471,46 @@ function registerPiTool(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, options, theme) {
+            const details = (result.details ?? {});
             if (options.isPartial) {
-                return new Text(theme.fg("warning", "⏳ Waiting for the user to submit…"), 0, 0);
+                if (details.url) {
+                    const pending = (details.names ?? []).join(", ");
+                    let text = theme.fg("accent", "🔗 Open this one-time link in your browser");
+                    if (pending)
+                        text += theme.fg("dim", ` — submit ${pending}`);
+                    text += `\n${theme.fg("toolTitle", theme.bold(details.url))}`;
+                    text += `\n${theme.fg("warning", "⏳ Waiting for submission…")}${theme.fg("muted", "   esc to cancel")}`;
+                    return new Text(text, 0, 0);
+                }
+                return new Text(theme.fg("warning", "⏳ Starting pinchpass…"), 0, 0);
             }
-            const details = (result.details ?? {});
             const success = details.success === true;
             const aborted = details.aborted === true;
             const names = (details.names ?? []).join(", ");
-            const bg = success ? "toolSuccessBg" : aborted ? "toolPendingBg" : "toolErrorBg";
-            const box = new Box(1, 1, (t) => theme.bg(bg, t));
             const statusColor = success ? "success" : aborted ? "warning" : "error";
             const head = success
                 ? "✅  Secrets collected"
                 : aborted
                     ? "✋  Cancelled"
                     : `❌  ${details.message ?? "Failed"}`;
-            box.addChild(new Text(theme.fg("toolTitle", theme.bold(head))));
+            let text = theme.fg("toolTitle", theme.bold(head));
             if (names)
-                box.addChild(new Text(theme.fg(statusColor, `     ${names}`)));
+                text += `\n${theme.fg(statusColor, `     ${names}`)}`;
             if (options.expanded) {
-                box.addChild(new Text(""));
+                if (details.via)
+                    text += `\n${theme.fg("dim", `     via: ${details.via}`)}`;
                 if (details.url)
-                    box.addChild(new Text(theme.fg("dim", `     Link: ${details.url}`)));
+                    text += `\n${theme.fg("dim", `     Link: ${details.url}`)}`;
                 if (details.out)
-                    box.addChild(new Text(theme.fg("dim", `     Saved to: ${details.out}`)));
+                    text += `\n${theme.fg("dim", `     Saved to: ${details.out}`)}`;
                 if (details.message)
-                    box.addChild(new Text(theme.fg("muted", `     ${details.message}`)));
-                box.addChild(new Text(""));
+                    text += `\n${theme.fg("muted", `     ${details.message}`)}`;
+                text += "\n";
                 for (const line of PINCHPASS_ART.split("\n")) {
-                    box.addChild(new Text(theme.fg("muted", `     ${line}`)));
+                    text += `\n${theme.fg("muted", `     ${line}`)}`;
                 }
             }
-            return box;
+            return new Text(text, 0, 0);
         },
     });
 }
@@ -483,16 +537,10 @@ async function registerOpenClawTool(api) {
                         .describe("Create a public URL via bore.pub tunnel (default: false)"),
                     note: tool.schema.string().optional().describe("Description shown on the form to help the user"),
                     ttl: tool.schema.number().optional().describe("Minutes until the link expires (default: 30)"),
+                    out: tool.schema.string().optional().describe("Output .env file path (default: .env)"),
                 },
                 async execute(args) {
-                    const binary = findBinary() ?? "pinchpass";
-                    const pieces = [binary, "request", ...args.names, "-json"];
-                    if (args.tunnel)
-                        pieces.push("-tunnel");
-                    if (args.note)
-                        pieces.push("-note", args.note);
-                    if (args.ttl)
-                        pieces.push("-ttl", String(args.ttl));
+                    const pieces = [findBinary() ?? "pinchpass", ...buildArgs(args)];
                     try {
                         const result = await api.$.raw(pieces);
                         return result?.stdout ||