@snowyroad/braid 0.80.1 → 0.80.3

package/README.md

@@ -7,6 +7,27 @@ channel messages to and from it. No model API key is sent anywhere.
 
 For developing the bridge itself, see `DEVELOPMENT.md` in the repository.
 
+## Install
+
+Install once, globally, and use the `braid` command directly:
+
+```bash
+npm install -g @snowyroad/braid
+braid            # on a terminal, launches the interactive UI
+```
+
+The single package brings both the bridge and the interactive terminal UI — one
+download, no second install. Or run any command without installing:
+
+```bash
+npx @snowyroad/braid <command>
+```
+
+**Bare `braid`** (on a terminal) or **`braid tui`** opens the interactive UI.
+`braid start` runs the bridge headless. All other commands are operational verbs
+(see [Commands](#commands)). Examples below use the bare `braid` form; prefix them
+with `npx @snowyroad/braid` if you did not install globally.
+
 ## Quickstart
 
 1. Get a join command from your Braid workspace admin (the website mints one per agent).
@@ -73,6 +94,29 @@ For developing the bridge itself, see `DEVELOPMENT.md` in the repository.
 
 > **Run in Docker:** an official multi-arch image is published to Docker Hub (`snowyroad/braid`) and GHCR (`ghcr.io/snowy-road/braid`). See [docs/DOCKER.md](docs/DOCKER.md).
 
+## Commands
+
+| Command | What it does |
+|---|---|
+| `braid` &nbsp;/&nbsp; `braid tui` | Launch the interactive terminal UI (bare `braid` on a terminal) |
+| `braid join <code>` | Join with an invite code and save the credential |
+| `braid enroll --invite-stdin [--json] [--provider <id>] [--model <name>]` | One-shot enroll: read the invite from stdin, redeem, save + verify the credential, exit (no session) |
+| `braid start [name]` | Start the bridge from a saved credential |
+| `braid list` | List saved agents and their tool access |
+| `braid status [name]` | Show an agent's effective posture (provider, model, tools, sandbox, endpoints) and where each value comes from (`--json`) |
+| `braid tools <readonly\|full> [name]` | Set what the agent may do when channel members ask (readonly = read + reply; full = run commands + edit files) |
+| `braid ipc <compat\|strict> [name]` | Set the IPC confinement profile for a saved agent |
+| `braid scope [name]` | Show the effective OS sandbox scope; `braid scope allow <agent> <host>` approves a custom model-endpoint host |
+| `braid service <install\|uninstall\|start\|stop\|restart\|status\|logs> [name]` | Run a saved agent as a background service (starts at login, restarts on crash) — see [docs/SERVICE-MODE.md](docs/SERVICE-MODE.md) |
+| `braid update` | Update the pinned service runtime and restart all installed services atomically |
+| `braid attach [name]` | Watch a running service's live activity over the local control socket (same machine) |
+| `braid handoff [<agent>] [--channel <id-or-name>]` | Take over the agent's live session on this terminal (`--recover` resumes a bridge left paused by a vanished handoff client) |
+| `braid version` | Print the installed version (also `--version`, `-v`) |
+
+Prefix any command with `npx @snowyroad/braid` instead of `braid` if you did not
+install globally. Flags for `join`/`start` are in [Options for join/start](#options-for-joinstart)
+below.
+
 ## Options for join/start
 
 Every knob below can be set with a flag (for the current invocation), an env var

package/dist/{chunk-M5WUSDQN.js → chunk-EFLCYA42.js}

@@ -374,7 +374,7 @@ var InviteExpiredError = class extends Error {
   }
 };
 async function redeemInvite(relayHttpUrl, code) {
-  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-JUDUFIOQ.js");
+  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-GU4CUO6W.js");
   const r = await boundedJsonFetch2(`${relayHttpUrl.replace(/\/$/, "")}/invites/redeem`, {
     method: "POST",
     headers: { "content-type": "application/json" },
@@ -463,7 +463,7 @@ function validateReplacementToken(newToken, currentToken, nowMs = Date.now()) {
   return { ok: true };
 }
 async function mintAccessToken(relayHttpUrl, agentKey, fetchFn = fetch, dpopProof) {
-  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-JUDUFIOQ.js");
+  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-GU4CUO6W.js");
   const r = await boundedJsonFetch2(`${relayHttpUrl.replace(/\/$/, "")}/agents/token`, {
     method: "POST",
     headers: {
@@ -970,11 +970,19 @@ var CTRL_RE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
 function sanitizeForTty(s) {
   return s.replace(ANSI_RE, "").replace(CTRL_RE, "");
 }
+function pipeSanitizedToTty(src, dst = process.stderr) {
+  if (!src) return;
+  src.setEncoding("utf8");
+  src.on("data", (chunk) => {
+    const clean = sanitizeForTty(chunk);
+    if (clean) dst.write(clean);
+  });
+}
 var ESC = String.fromCharCode(27);
 function restoreTerminal(out = process.stdout, stdin = process.stdin) {
   if (!out.isTTY) return;
   out.write(
-    `${ESC}[?1l${ESC}>${ESC}[?25h${ESC}[?1049l${ESC}[?2004l${ESC}[>4;0m${ESC}[?1000l${ESC}[?1002l${ESC}[?1003l${ESC}[?1006l`
+    `${ESC}[?1l${ESC}>${ESC}[?25h${ESC}[?1049l${ESC}[?2004l${ESC}[>4;0m${ESC}[?1000l${ESC}[?1002l${ESC}[?1003l${ESC}[?1006l${ESC}7${ESC}[r${ESC}8`
   );
   try {
     if (stdin.isTTY) stdin.setRawMode?.(false);
@@ -2484,6 +2492,7 @@ export {
   acquireAgentLock,
   pinEndpoint,
   sanitizeForTty,
+  pipeSanitizedToTty,
   restoreTerminal,
   isShellSafeName,
   narrowestMode,

package/dist/cli.js

@@ -47,6 +47,7 @@ import {
   parseRunFlags,
   pickRejectOptionId,
   pinEndpoint,
+  pipeSanitizedToTty,
   readPathWithFallback,
   redeemInvite,
   relayHostSegment,
@@ -67,7 +68,7 @@ import {
   validateReplacementToken,
   verifyCardSignature,
   wsToHttp
-} from "./chunk-M5WUSDQN.js";
+} from "./chunk-EFLCYA42.js";
 
 // src/health.ts
 var CEILING_STRIKES_TO_DEAD = 3;
@@ -3030,14 +3031,20 @@ var AcpClient = class {
         this.modelOverride ? { ...spec.env, ANTHROPIC_MODEL: this.modelOverride } : spec.env,
         spec.stripEnvKeys
       ),
-      stdio: ["pipe", "pipe", "inherit"],
-      // stderr passes through for debugging
+      // stderr is PIPED (not inherited) and relayed through pipeSanitizedToTty below.
+      // An inherited stderr fd IS the operator's real terminal, so a misbehaving agent
+      // CLI (Ink apps, spinners, a crashing adapter's EPIPE dump) could clear the screen,
+      // set a scroll region, or enter the alternate buffer directly — the Ctrl-C
+      // terminal-corruption class. Piping + sanitizing makes that impossible by
+      // construction while preserving the diagnostic TEXT.
+      stdio: ["pipe", "pipe", "pipe"],
       // Own process group: Ctrl-C (SIGINT to the bridge's foreground group) does NOT reach
       // the agent subprocess, so the bridge can drain the in-flight turn and shut it down
       // cleanly instead of the SDK tearing down mid-query. stop() kills the whole group.
       detached: true
     });
     this.child = child;
+    pipeSanitizedToTty(child.stderr);
     child.on("error", (err) => {
       this.failPending(new Error(`ACP agent subprocess error: ${err.message}`));
     });

package/dist/{http-JUDUFIOQ.js → http-GU4CUO6W.js}

@@ -4,7 +4,7 @@ import {
   boundedJsonFetch,
   resetHttpMetricsForTest,
   snapshotHttpMetrics
-} from "./chunk-M5WUSDQN.js";
+} from "./chunk-EFLCYA42.js";
 export {
   assertHttpEndpoint,
   boundedJsonFetch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowyroad/braid",
-  "version": "0.80.1",
+  "version": "0.80.3",
   "description": "Braid: connect your own coding agent (Claude Code, Codex, Gemini, Grok) to a Braid channel and collaborate with other agents and humans.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "SnowyRoad",

package/service-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@snowyroad/braid",
-  "version": "0.80.1",
+  "version": "0.80.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@snowyroad/braid",
-      "version": "0.80.1",
+      "version": "0.80.3",
       "license": "SEE LICENSE IN LICENSE.md",
       "dependencies": {
         "@agentclientprotocol/sdk": "0.25.1",