@cursor/july 0.1.39 → 0.1.41

package/docs/guides/webhooks.md

@@ -177,6 +177,18 @@ swaps the default for `bearerAuth` on every channel that doesn't author
 its own chain, and `--allow-anonymous` swaps it for `allowAll()`
 (trusted networks only). Authored `auth` arrays always win over both.
 
+## Hosted aliases need an alias-token relay
+
+Cursor-managed deployments expose a stable alias URL. External callers
+must send `X-Agent-Alias-Token` on every request to that URL. Channel
+auth still runs after the alias gate.
+
+Webhook providers that cannot attach custom headers cannot POST
+straight at a managed alias. Put a relay (or other authenticating
+intermediary) in front, use a Cursor-managed ingress path that does not
+use the public alias (for example Cursor Slack / GitHub event relay),
+or self-host. See [Deployment](../deployment.md#use-the-hosted-agent).
+
 ## Example: Linear as the control plane
 
 Everything above composes into a working ticket-driven agent. This
@@ -346,6 +358,81 @@ See [MCP connections](../reference/connections.md) for the direct
 `https://mcp.linear.app/mcp` form when the host isn't signed in to
 Cursor.
 
+### Production Linear agents: expiring OAuth tokens
+
+A plain API key fits a personal integration. A production Linear agent
+is an OAuth application: installing it in a workspace mints an access
+token with an expiry plus a refresh token. The serve host can be
+replaced at any time, so the pair can't live in process memory.
+Persist it in [`host.kv`](../storage.md#author-kv-ctx-host-kv) instead.
+Route handlers receive `host` in their args, and event handlers get the
+same services on `ctx`.
+
+Two prerequisites:
+
+- Keep the OAuth client id and client secret in
+  [deployment secrets](../deployment.md). They're static, so
+  deploy-time env vars fit them.
+- Back kv with durable storage. On Cursor-managed hosting, use
+  `cursorHostedStorage` in `agent/storage.ts`
+  ([Storage](../storage.md)). Without it, kv falls back to local disk
+  and a host replacement drops the tokens.
+
+Save the pair when the install flow completes, then refresh on demand:
+
+```ts
+import type { HostKvApi } from "@cursor/july/kv";
+
+interface LinearTokens {
+  accessToken: string;
+  refreshToken: string;
+  expiresAtMs: number;
+}
+
+const TOKENS_KEY = "linear/oauth-tokens";
+
+export async function linearAccessToken(kv: HostKvApi): Promise<string> {
+  const tokens = (await kv.get(TOKENS_KEY)) as LinearTokens | undefined;
+  if (tokens === undefined) {
+    throw new Error("No Linear tokens stored. Complete the install flow first.");
+  }
+  if (Date.now() < tokens.expiresAtMs - 60_000) {
+    return tokens.accessToken;
+  }
+  const response = await fetch("https://api.linear.app/oauth/token", {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: tokens.refreshToken,
+      client_id: process.env.LINEAR_CLIENT_ID ?? "",
+      client_secret: process.env.LINEAR_CLIENT_SECRET ?? "",
+    }),
+  });
+  if (!response.ok) {
+    throw new Error(`Linear token refresh failed: ${response.status}`);
+  }
+  const next = (await response.json()) as {
+    access_token: string;
+    refresh_token?: string;
+    expires_in: number;
+  };
+  const rotated: LinearTokens = {
+    accessToken: next.access_token,
+    refreshToken: next.refresh_token ?? tokens.refreshToken,
+    expiresAtMs: Date.now() + next.expires_in * 1000,
+  };
+  await kv.put(TOKENS_KEY, rotated);
+  return rotated.accessToken;
+}
+```
+
+Then authorize GraphQL calls with `Bearer ${await
+linearAccessToken(host.kv)}` in place of the static `apiKey` above.
+Writes to `host.kv` await the durable sink and propagate errors, so a
+failed save surfaces instead of silently losing the rotated refresh
+token.
+
 To test without a public URL, save a payload from the webhook's
 delivery log (or the sample in
 [Linear's webhook docs](https://linear.app/developers/webhooks)) under

package/docs/quickstart.md

@@ -21,9 +21,8 @@ You need:
 - Node 22.13 or newer. Bun isn't supported.
 - The `agent-sdk` CLI. `npx @cursor/july init ./pr-approver` bootstraps
   it with no prior install: `init` scaffolds the project, runs
-  `npm install`, and offers a Cursor sign-in, after which `npx agent-sdk`
-  resolves from the project's own dependencies. See
-  [Run the CLI](./README.md#run-the-cli) for other setups, such as a
+  `npm install`, links `agent-sdk` onto your PATH, and offers a Cursor
+  sign-in. See [Run the CLI](/#run-the-cli) for other setups, such as a
   monorepo source checkout.
 - A Cursor credential for model turns. Sign in once:
 
@@ -44,9 +43,9 @@ Want a working agent before the full tutorial? Four commands get you
 there:
 
 ```bash
-agent-sdk init ./pr-approver     # scaffold + npm install + sign-in offer
+npx @cursor/july init ./pr-approver     # scaffold + npm install + PATH link + sign-in offer
 cd pr-approver
-agent-sdk dev                    # serve, and print the playground URL
+agent-sdk dev                           # serve, and print the playground URL
 ```
 
 Open the playground URL and chat with the scaffold. Then, in a second
@@ -79,7 +78,7 @@ full guided workflow.
 Start with the built-in scaffold:
 
 ```bash
-agent-sdk init ./pr-approver
+npx @cursor/july init ./pr-approver
 cd pr-approver
 agent-sdk dev
 ```
@@ -299,7 +298,7 @@ Call the tool directly first, on a real merged pull request:
 
 ```bash
 agent-sdk call inspect_pr --dir . \
-  --input '{"prUrl":"https://github.com/react/react/pull/35623"}'
+  --input '{"prUrl":"https://github.com/facebook/react/pull/35623"}'
 ```
 
 `call` validates the input and runs `execute` without a model turn.
@@ -322,7 +321,7 @@ Now call it on the PR that added `experimental_useEvent` to React:
 
 ```bash
 agent-sdk call inspect_pr --dir . \
-  --input '{"prUrl":"https://github.com/react/react/pull/25229"}'
+  --input '{"prUrl":"https://github.com/facebook/react/pull/25229"}'
 ```
 
 The rating flips to `large` and the patches disappear from the result.

package/docs/reference/cli.md

@@ -11,7 +11,7 @@ page use `agent-sdk`. Run the CLI with Node 22.13 or newer. Don't run it
 with Bun; Bun corrupts tool-result streams from the Cursor SDK.
 
 The current release still uses `.agent-serve` for on-disk state. See the
-[rename table](../README.md#run-the-cli) for identifiers still moving to
+[rename table](/#run-the-cli) for identifiers still moving to
 agent-sdk names.
 
 `agent-sdk help` prints the built-in summary. The Slack and GitHub packs
@@ -111,7 +111,7 @@ Unless `--state-root` is set, each mount uses
 
 | Flag | Meaning |
 | --- | --- |
-| `--port` | Listen on this port. `0` selects an available port. The default is `3000`. |
+| `--port` | Listen on this port. `0` selects an available port. The default is `3000`. When the default is taken, serve tries the next free port and prints a notice; an explicit `--port` fails with a next-port hint instead. |
 | `--host` | Bind this host. The default is loopback-only `127.0.0.1`. |
 | `--dev` | Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, widen playground session access on loopback, and start Vite HMR when available. |
 | `--mode` | Use `multi` for slugged routes and an index, or `single` for one agent at the unslugged `/v1/*`. The default is `multi`. |
@@ -733,14 +733,23 @@ See the [Host MCP OAuth guide](../guides/mcp-oauth.md).
 `secrets` manages environment secrets for a deployment.
 
 ```bash
-agent-sdk secrets set <slug> NAME[=VALUE]... [--team <id>] [--json]
+agent-sdk secrets set <slug> NAME [NAME2 ...] [--team <id>] [--json]
 agent-sdk secrets list <slug> [--team <id>] [--json]
 agent-sdk secrets unset <slug> NAME [--team <id>] [--json]
 ```
 
-Omit `=VALUE` from `secrets set` to enter the value at a hidden TTY
-prompt. With piped stdin, provide one line for each missing value. Avoid
-values in command arguments because shells can record them in history.
+Pass names only. On a TTY, `secrets set` prompts for each value with
+hidden input (nothing echoes). When stdin is piped, provide one line per
+name. Values never print on stdout.
+
+Do not put values on the command line. `NAME=VALUE` in argv shows up in
+shell history and in agent-captured terminals. The CLI refuses that form
+unless you pass `--from-argv` (still warns). Prefer a file redirect when
+a human is not at the prompt:
+
+```bash
+agent-sdk secrets set weather-agent WEATHER_API_KEY < ./weather-api-key.txt
+```
 
 Secret names use `UPPER_SNAKE_CASE`, start with a letter, and contain at
 most 64 characters. Names beginning with `CURSOR_` are reserved. Values

package/docs/reference/hooks.md

@@ -9,8 +9,14 @@ A hook is an observe-only subscriber to the session event stream. Hooks
 run after each event is recorded and fanned out (file persistence flushes
 in the background). That makes them the home for audit logging, metrics,
 mirroring transcripts into your own store, and maintaining derived state.
-Handler errors are logged and never fatal. A hook can't modify events or
-block a turn.
+Handler errors are logged and never fatal. A hook can't modify events,
+inject context into the next turn, or block a turn.
+
+For deterministic context composition before the model runs, use the
+host path that already owns the wake: channel handlers (fetch, `callTool`,
+`workspaceFiles`, and the message you pass to `send`), plus
+`instructions.md`, skills, and `sandbox/workspace/` seed files. Hooks
+observe what happened; they do not assemble the prompt.
 
 Author `agent/hooks/<name>.ts` with `defineHook` from
 `@cursor/july/hooks`:

package/docs/storage.md

@@ -22,7 +22,10 @@ for one machine; it does not survive replacing the host.
 
 To keep the same framework storage across hosts, plug in a key-value
 backend with `agent/storage.ts`. You provide `put` / `get` / `delete` /
-`list`. The Agent SDK does the rest.
+`list`, plus the `cas` group when the deployment uses coordination
+features (conditional writes — see
+[Conditional writes](#conditional-writes-the-cas-group)). The Agent SDK
+does the rest.
 
 ```ts
 // agent/storage.ts
@@ -33,26 +36,33 @@ export default defineStorage({
   get: (key) => db.get(key),
   delete: (key) => db.delete(key),
   list: (prefix) => db.listByPrefix(prefix), // [{ key, value }], key order
+  cas: {
+    getWithVersion: (key) => db.getRow(key), // { value, version }
+    putIfAbsent: (key, value) => db.insertIfAbsent(key, value),
+    putIfVersion: (key, value, expected) => db.casUpdate(key, value, expected),
+    listKeys: (prefix) => db.listKeysByPrefix(prefix),
+  },
 });
 ```
 
 > [!NOTE]
 > Import paths here use `@cursor/july/storage`. On projects still
 > using `@anysphere/agent-serve`, swap the import. See
-> [Run the CLI](./README.md#run-the-cli) for the full rename table.
+> [Run the CLI](/#run-the-cli) for the full rename table.
 
 ## Which fields to provide
 
 | Field | Required | Role |
 | --- | --- | --- |
 | `put` | Yes | Write or update a value |
+| `cas` | For coordination | Conditional writes; see [Conditional writes](#conditional-writes-the-cas-group) |
 | `get` | For restore | Look up one key |
 | `list` | For restore | Return entries under a prefix, in key order |
 | `delete` | For cleanup | Remove a key |
 | `name` | No | Label surfaced on `GET /v1/info` diagnostics |
 | `policy` | No | Timing knobs; see [Policy](#policy) |
-| `evals` | No | Dedicated eval-runs table; see [Eval and A/B tables](#eval-and-ab-tables) |
-| `abs` | No | Dedicated A/B metrics table; see [Eval and A/B tables](#eval-and-ab-tables) |
+| `evals` | No | Dedicated eval-runs table; see [Eval and A/B tables](#eval-and-a-b-tables) |
+| `abs` | No | Dedicated A/B metrics table; see [Eval and A/B tables](#eval-and-a-b-tables) |
 
 A throwing `put` is logged and dropped. It never fails a turn. When
 resolving a missing continuation token, a throwing `get` fails the
@@ -142,8 +152,6 @@ survive replacing the host. For Cursor-managed hosting, prefer
 `@cursor/july/storage/cursor-hosted` so sessions and author KV share the
 platform Bugbot tables through a control-plane HTTP proxy (authenticated
 as the deployment pod credential — engines never receive a database URL).
-For self-hosted Postgres you own, use `@cursor/july/storage/postgres-kv`
-and supply `BUGBOTDB_URL` / `AGENT_SERVE_DEPLOYMENT_ID` yourself.
 
 ```ts
 // agent/storage.ts — Cursor-managed hosting
@@ -161,4 +169,56 @@ Built-in helpers:
 | --- | --- |
 | `@cursor/july/storage/file-kv` | File-per-key under `.agent-serve/kv` |
 | `@cursor/july/storage/cursor-hosted` | Platform Bugbot `agent_serve_*` via control-plane proxy |
-| `@cursor/july/storage/postgres-kv` | Same tables; you supply `BUGBOTDB_URL` / `AGENT_SERVE_DEPLOYMENT_ID` |
+
+## Bring your own backend
+
+There is no built-in Postgres backend on purpose. Cursor's internal
+`agent_serve_*` tables are owned by the backend and reachable only
+through the hosted proxy, and this doc does not prescribe a schema —
+what you back the KV with is your call. Any durable store works:
+
+- **Local disk** — the built-in `fileKv` (single process only).
+- **Object storage (S3-class)** — one object per key; conditional
+  writes map directly onto the contract (`putIfAbsent` = put with
+  `If-None-Match: *`, `putIfVersion` = put with `If-Match: <etag>`,
+  the ETag is the version token, `listKeys` is a prefix listing).
+- **Redis, DynamoDB, a SQL table, …** — anything that can do an
+  atomic compare-and-set and a prefix listing.
+
+Implement the `StorageConfig` methods (and the `cas` group when the
+deployment uses coordination features) against that store. The
+contract, defined at `@cursor/july/kv`: version tokens are opaque
+strings that change on every successful write — including plain
+`put`, so a stale token fences instead of clobbering; conditional
+writes are atomic; `listKeys` returns every key under the prefix.
+`@cursor/july/kv/memory` is a complete reference implementation to
+compare behavior against.
+
+## Conditional writes (the `cas` group)
+
+The `cas` group is compare-and-swap over the same keyspace:
+`getWithVersion` / `putIfAbsent` / `putIfVersion` / `listKeys`, defined
+backend-agnostically at `@cursor/july/kv`. Plain storage works without
+it, so an existing backend keeps working across a platform upgrade.
+Coordination features require it: they fail at startup, with a message
+naming this group, when the backend lacks it. `defineStorage` rejects a
+partial group — implement all four methods or none. Version tokens are
+opaque strings that must change on every write (a counter column, a row
+version, a content hash). The built-in backends both include it: `fileKv`
+uses content-hash tokens (single-process correctness) and
+`cursorHostedStorage` the control-plane proxy (a `version` counter on the
+server).
+
+## Durable sessions (the session ledger)
+
+Conditional writes are the substrate for the session ledger, which
+ships behind `defineAgent({ serving: "ledger" })`: session identity,
+one-writer-per-session leases with generation fencing, and a fenced
+commit sequence, coordinated through the agent's storage backend by
+default (its `cas` group) or an explicit `durableSessionStore`
+override. The ledger has **no durable inbox** — an event arriving while
+a session's lease is held waits in-process on the delivering pod, so
+crash durability matches resident serving; what ledger mode adds is
+cross-pod mutual exclusion, zombie fencing, and the committed head
+sequence. A backend that implements `cas` needs no storage migration to
+adopt it.

package/docs/troubleshooting.md

@@ -13,7 +13,7 @@ Start with four checks, in order:
 4. The session event stream (trace)
 
 Match your symptom below. Keep the commands as `agent-sdk`; see
-[Run the CLI](./README.md#run-the-cli) if you still need an alias.
+[Run the CLI](/#run-the-cli) if you still need an alias.
 
 ## What if serve or the playground looks wrong?
 
@@ -23,7 +23,7 @@ Match your symptom below. Keep the commands as `agent-sdk`; see
 | Playground is blank or says there are no agents | The UI needs a running `serve` process. Building the playground assets alone is not enough. |
 | Edits to the playground don't show up | Use `serve --dev` and open the printed playground HMR URL (often port `5273`), not only the static `:3000` URL. |
 | Sessions exist on disk but the playground list is empty | The list shows sessions for the authenticated caller. In `--dev` on loopback the list is wider. Otherwise open `/<slug>/playground?sessionId=ses_…` or inspect `sessions/` under your state root. |
-| Port 3000 or 5273 is already in use | Find and stop the listener (`lsof -iTCP:3000 -sTCP:LISTEN` on macOS/Linux), and any leftover Vite or webhook-forwarder processes. |
+| Port 3000 or 5273 is already in use | For the default serve port, the CLI tries the next free port and prints a notice. Pass `--port` to pick one, or `--port 0` for any free port. Stop leftover Vite or webhook-forwarder processes if you need the original port. |
 
 ## What if a model turn goes wrong?
 
@@ -75,6 +75,14 @@ Match your symptom below. Keep the commands as `agent-sdk`; see
 See [Host MCP OAuth](./guides/mcp-oauth.md) and
 [`skills/mcp-auth/SKILL.md`](../skills/mcp-auth/SKILL.md).
 
+## What if a secret showed up in a terminal transcript?
+
+| What you see | What to do |
+| --- | --- |
+| `secrets set … NAME=VALUE` in an agent-captured terminal or shell history | Rotate the secret at the provider. Set it again with names only: `agent-sdk secrets set <slug> NAME` (hidden prompt) or pipe/redirect the value. `NAME=VALUE` requires `--from-argv` and still leaks into argv. |
+| Alias token printed during first deploy or `rotate-token` | Treat it as exposed if the transcript left your machine. Run `agent-sdk rotate-token <slug>`, store the new token outside agent transcripts, and update callers. |
+| Someone verified a secret with `echo` / `printenv` | Rotate it. Confirm presence with `agent-sdk secrets list <slug>` (names only), then redeploy and test the feature. |
+
 ## What if schedules, reminders, or approvals stall?
 
 | What you see | What to do |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -141,6 +141,24 @@
       "import": "./dist/artifacts.js",
       "default": "./dist/artifacts.js"
     },
+    "./kv": {
+      "anysphere-source": "./src/kv.ts",
+      "types": "./dist/kv.d.ts",
+      "import": "./dist/kv.js",
+      "default": "./dist/kv.js"
+    },
+    "./kv/memory": {
+      "anysphere-source": "./src/kv/memory-kv.ts",
+      "types": "./dist/kv/memory-kv.d.ts",
+      "import": "./dist/kv/memory-kv.js",
+      "default": "./dist/kv/memory-kv.js"
+    },
+    "./ledger": {
+      "anysphere-source": "./src/ledger.ts",
+      "types": "./dist/ledger.d.ts",
+      "import": "./dist/ledger.js",
+      "default": "./dist/ledger.js"
+    },
     "./storage": {
       "anysphere-source": "./src/storage.ts",
       "types": "./dist/storage.d.ts",
@@ -153,12 +171,6 @@
       "import": "./dist/storage-backends/file-kv.js",
       "default": "./dist/storage-backends/file-kv.js"
     },
-    "./storage/postgres-kv": {
-      "anysphere-source": "./src/storage-backends/postgres-kv.ts",
-      "types": "./dist/storage-backends/postgres-kv.d.ts",
-      "import": "./dist/storage-backends/postgres-kv.js",
-      "default": "./dist/storage-backends/postgres-kv.js"
-    },
     "./storage/cursor-hosted": {
       "anysphere-source": "./src/storage-backends/cursor-hosted.ts",
       "types": "./dist/storage-backends/cursor-hosted.d.ts",
@@ -182,6 +194,7 @@
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
+    "docs:verify-links": "node scripts/verify-docs-links.mjs",
     "fix": "biome check --write --unsafe src",
     "test": "vitest run --passWithNoTests",
     "type-check": "tsgo --noEmit && tsgo --noEmit -p playground/tsconfig.json",

package/skills/create-agent/SKILL.md

@@ -144,7 +144,7 @@ a demo `agent/tools/echo.ts`, and empty capability folders
 (`skills/`, `channels/`, `evals/`, …) each with a `.gitkeep`; existing
 files are left alone (`exist`) and missing ones are filled in. It then
 runs `npm install`, and when the host is unsigned runs `login` and waits
-before printing `cd` (when needed) and bare `dev`. Then shape it to the
+before printing `cd` (when needed) and `agent-sdk dev`. Then shape it to the
 plan:
 
 1. `tsconfig.json` — init writes a strict, `noEmit` config covering `agent/`

package/src/bin/agent-serve.ts

@@ -136,8 +136,8 @@ Usage:
   ${CLI} stop        <slug> [--team <id>] [--json] [--no-wait]
   ${CLI} rotate-token <slug> [--team <id>]
   ${CLI} rotate-pod-credential <slug> [--team <id>]
-  ${CLI} secrets     set <slug> NAME[=VALUE]... | list <slug> | unset <slug> NAME
-                          [--team <id>] [--json]
+  ${CLI} secrets     set <slug> NAME... | list <slug> | unset <slug> NAME
+                          [--team <id>] [--json] [--from-argv]
   ${CLI} slack       <subcommand> …
   ${CLI} github      <subcommand> …
 
@@ -257,9 +257,9 @@ Commands:
   rotate-pod-credential
               Rotate a deployment's pod credential (prints the masked key);
               the running pod keeps the old one until the next deploy.
-  secrets     Manage deployment secrets: set (upsert by name; NAMEs without
-              =VALUE are prompted for with hidden input, or read from piped
-              stdin), list (names + createdAt; never values), unset.
+  secrets     Manage deployment secrets: set (names only by default: hidden
+              prompt or piped stdin; NAME=VALUE requires --from-argv), list
+              (names + createdAt; never values), unset.
   slack       Slack channel pack: create/destroy/icon (Cursor Add to Slack
               provisioning), init, manifests, doctor (see slack help).
   github      GitHub webhook pack: forward live deliveries, events, doctor
@@ -276,7 +276,9 @@ Agent loop:
 Options:
   --version, -V      Print the installed version and exit.
   --dir             Project root (defaults to the current directory).
-  --port             Port to listen on (default 3000).
+  --port             Port to listen on (default 3000). When the default is
+                     taken, serve tries the next free port and prints a notice.
+                     An explicit --port fails with a next-port hint instead.
   --host             Host to bind (default 127.0.0.1).
   --mode             serve: "multi" (default, slugged /<dir>/v1/*) or "single"
                      (unslugged /v1/*). Multi also exposes host /v1/health for
@@ -402,6 +404,9 @@ Options:
   --allow-domain     deploy: egress domain the engine pod may reach
                      (repeatable; unioned with hosting.egressDomains from the
                      agent manifest). Repo-backed deploys only.
+  --from-argv        secrets set: allow NAME=VALUE on argv (leaks into shell
+                     history and agent-captured terminals). Default is names
+                     only with a hidden prompt or piped stdin.
   --org              github forward: organization login (org-level hooks).
   --channel          github: select one channel id when several are declared.
   --secret           github forward: webhook signing secret (defaults to
@@ -535,6 +540,7 @@ async function main(argv: string[]): Promise<number> {
       all: { type: "boolean", default: false },
       "cursor-events-repo": { type: "string", multiple: true },
       "allow-domain": { type: "string", multiple: true },
+      "from-argv": { type: "boolean", default: false },
       strict: { type: "boolean", default: false },
       junit: { type: "string" },
       artifacts: { type: "string" },
@@ -1148,8 +1154,13 @@ async function main(argv: string[]): Promise<number> {
       }
       const serveDir = serveDirResult;
       const port =
-        values.port === undefined ? 3000 : Number.parseInt(values.port, 10);
-      if (Number.isNaN(port) || port < 0 || port > 65535) {
+        values.port === undefined
+          ? undefined
+          : Number.parseInt(values.port, 10);
+      if (
+        port !== undefined &&
+        (Number.isNaN(port) || port < 0 || port > 65535)
+      ) {
         process.stderr.write(`invalid --port: ${values.port}\n`);
         return 1;
       }
@@ -1303,12 +1314,14 @@ function deployOptionsFromValues(values: {
   json?: boolean;
   "no-wait"?: boolean;
   "api-key"?: string;
+  "from-argv"?: boolean;
 }): DeployCliOptions {
   return {
-    ...(values.team === undefined ? {} : { team: values.team }),
+    team: values.team,
     json: values.json === true,
     noWait: values["no-wait"] === true,
-    ...(values["api-key"] === undefined ? {} : { apiKey: values["api-key"] }),
+    apiKey: values["api-key"],
+    fromArgv: values["from-argv"] === true ? true : undefined,
   };
 }
 
@@ -1484,7 +1497,10 @@ function printServeBanner(
   if (playgroundUrl !== undefined) {
     process.stdout.write(`  playground  ${c.cyan(playgroundUrl)}\n`);
   }
-
+  // `/` is only mounted when the playground host home is enabled.
+  if (!opts.noPlayground) {
+    process.stdout.write(`  home        ${c.cyan(handle.url + "/")}\n`);
+  }
   // Dev is playground-first (Vite proxies the API). Keep API/route detail for
   // plain `serve`, where operators often curl the HTTP surface directly.
   if (!opts.dev) {

package/src/channels/slack/api.ts

@@ -204,25 +204,30 @@ export async function setThreadStatus(args: {
     return { ok: false, error: "missing_channel_or_thread" };
   }
   const status = truncateTypingStatus(args.status);
-  const loadingRaw =
-    args.loadingMessages !== undefined && args.loadingMessages.length > 0
-      ? args.loadingMessages
-      : status.length > 0
-        ? [
+  const body: Record<string, unknown> = {
+    channel_id: args.channelId,
+    thread_ts: args.threadTs,
+    status,
+  };
+  // Empty status clears Slack's assistant chip ("App is working…").
+  // Sending loading_messages with it keeps the chip rotating.
+  if (status.length > 0) {
+    const loadingRaw =
+      args.loadingMessages !== undefined && args.loadingMessages.length > 0
+        ? args.loadingMessages
+        : [
             status,
             ...SLACK_DEFAULT_LOADING_MESSAGES.filter((m) => m !== status),
-          ]
-        : [];
-  const loading_messages = truncateLoadingMessages(loadingRaw);
+          ];
+    const loading_messages = truncateLoadingMessages(loadingRaw);
+    if (loading_messages.length > 0) {
+      body.loading_messages = loading_messages;
+    }
+  }
   return callSlackApiSoft({
     botToken: args.botToken,
     operation: "assistant.threads.setStatus",
-    body: {
-      channel_id: args.channelId,
-      thread_ts: args.threadTs,
-      status,
-      ...(loading_messages.length > 0 ? { loading_messages } : {}),
-    },
+    body,
   });
 }