@stacksjs/defaults 0.75.336 → 0.75.339

package/ai/skills/stacks-buddy/SKILL.md

@@ -577,6 +577,8 @@ buddy upgrade                # upgrade Stacks framework (alias: update)
   --canary                   # upgrade to canary build
   --stable                   # switch to stable release
   -f/--force                 # force re-download
+  --dry-run                  # preview; marks any (downgrade) a real run refuses
+  --allow-downgrade          # accept a release older than the app's own pins
 buddy upgrade:all            # upgrade framework + dependencies + Bun + binary
 buddy upgrade:dependencies   # upgrade dependencies (alias: upgrade:deps)
 buddy upgrade:bun            # upgrade Bun runtime

package/ai/skills/stacks-chat/SKILL.md

@@ -513,15 +513,20 @@ Receipts acknowledge only messages through the id actually displayed.
 `send(id, body, retryKey, attachments?)` records files the application has
 already stored. The trait keeps a reference, never bytes: `file` is the
 application's own name for the upload (a disk path, a bucket key, an id), and
-`type`, `size`, `width` and `height` are optional. Resolving and authorizing
-the file stays with the application, so a disk, a bucket and a CDN look the
-same from here.
+`type`, `name`, `size`, `width` and `height` are optional. `name` is what the
+sender called the file (`Week 42 plan.pdf`): `file` is an unguessable stored
+name, so for a document `name` is the only thing that tells the recipient what
+they were sent. Resolving and authorizing the file stays with the application,
+so a disk, a bucket and a CDN look the same from here.
 
 ```ts
 import type { DirectMessageAttachment } from '@stacksjs/chat'
 
 const photo: DirectMessageAttachment = { file: upload.key, type: 'image/jpeg', size: upload.size, width: 1200, height: 900 }
 await messenger.send(thread.id, '', retryKey, [photo])
+
+const plan: DirectMessageAttachment = { file: upload.key, type: 'application/pdf', name: upload.originalName, size: upload.size }
+await messenger.send(thread.id, '', retryKey, [plan])
 ```
 
 - A photo with no caption is a message: `body` may be empty when there is at
@@ -531,8 +536,10 @@ await messenger.send(thread.id, '', retryKey, [photo])
 - A retry key covers the attachments too. The same key with a different file
   is a different message and returns 409, rather than silently keeping the
   first photo.
-- At most 10 attachments, 4000 characters once serialised. Keys the trait does
-  not know are dropped, so the column cannot become a second message body.
+- At most 10 attachments, 4000 characters once serialised. `type` and `name`
+  are 1 to 255 characters. A key the trait does not know is refused with a 422
+  that names it, rather than dropped, so the column cannot become a second
+  message body and nothing a caller sent goes missing silently.
 - The column is `chat_messages.attachments`, added by `buddy migrate` to a
   database created before it. A database that has not migrated yet still sends
   text.

package/ai/skills/stacks-env/SKILL.md

@@ -194,6 +194,20 @@ autoLoadEnv()  // .env, .env.local, .env.<effectiveEnv>, .env.<effectiveEnv>.loc
 envPlugin()
 ```
 
+To keep a key out of a child process, withhold it rather than deleting it.
+`delete process.env.X` before a spawn does nothing useful: Bun loads `.env`
+natively in the child and `loadEnv` fills anything absent, so the child reads
+the value straight back from disk (#3028). Pass `withholdEnv(keys)` into the
+child's `env` (it sets `STACKS_ENV_WITHHOLD`). `loadEnv` then skips those keys
+in every file and removes any copy Bun loaded natively; a child that runs no
+Stacks preload calls `applyWithheldEnv()` before reading config.
+
+```typescript
+import { withholdEnv } from '@stacksjs/env'
+
+await runAction(Action.BuildIos, { env: withholdEnv(['MOBILE_URL']) })
+```
+
 ## .env Parser
 
 ```typescript

package/ai/skills/stacks-mobile/SKILL.md

@@ -206,6 +206,12 @@ While an app is in TestFlight before its first public release, keep the iOS
 marketing version at `1.0.0` and run `buddy release:ios --bump build`. Each
 upload needs a new build number, not a patch to the marketing version.
 
+A release never reads dev-shell overrides. `release:ios` withholds
+`MOBILE_URL`, `IOS_APP_VERSION` and `IOS_BUILD_NUMBER` from its build child
+(`withholdEnv` from `@stacksjs/env`, since deleting them from `process.env` is
+undone by the child's own `.env` load), and refuses a generated
+`devServerURL` on a local address before committing or tagging (#3028).
+
 Each `release:ios` also creates the tag's GitHub release (the TestFlight build
 number and the changes since the previous tag), using `GITHUB_TOKEN`,
 `GH_TOKEN`, the GitHub CLI's token or the git credential. When that fails the

package/ai/skills/stacks-native/CATALOG.md

@@ -11,8 +11,8 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | Package | Task guidance | Source entry | Retained tests |
 |---|---|---|---|
 | `@stacksjs/action-runner` | [`stacks-actions`](../stacks-actions/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/action-runner/src/index.ts) | 1 |
-| `@stacksjs/actions` | [`stacks-actions`](../stacks-actions/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/index.ts) | 89 |
-| `@stacksjs/ai` | [`stacks-ai`](../stacks-ai/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/index.ts) | 17 |
+| `@stacksjs/actions` | [`stacks-actions`](../stacks-actions/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/index.ts) | 91 |
+| `@stacksjs/ai` | [`stacks-ai`](../stacks-ai/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/index.ts) | 18 |
 | `@stacksjs/alias` | [`stacks-alias`](../stacks-alias/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/alias/src/index.ts) | 1 |
 | `@stacksjs/analytics` | [`stacks-analytics`](../stacks-analytics/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/analytics/src/index.ts) | 6 |
 | `@stacksjs/api` | [`stacks-api`](../stacks-api/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/api/src/index.ts) | 9 |
@@ -21,7 +21,7 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@stacksjs/auth` | [`stacks-auth`](../stacks-auth/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/index.ts) | 120 |
 | `@stacksjs/browser` | [`stacks-browser`](../stacks-browser/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/browser/src/index.ts) | 8 |
 | `@stacksjs/browser-extension` | [`stacks-browser-extension`](../stacks-browser-extension/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/browser-extension/src/index.ts) | 7 |
-| `@stacksjs/buddy` | [`stacks-buddy`](../stacks-buddy/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/src/index.ts) | 169 |
+| `@stacksjs/buddy` | [`stacks-buddy`](../stacks-buddy/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/src/index.ts) | 170 |
 | `@stacksjs/build` | [`stacks-build`](../stacks-build/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/build/src/index.ts) | 4 |
 | `@stacksjs/cache` | [`stacks-cache`](../stacks-cache/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/cache/src/index.ts) | 14 |
 | `@stacksjs/calendar-api` | [`stacks-calendar`](../stacks-calendar/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/calendar-api/src/index.ts) | 2 |
@@ -45,7 +45,7 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@stacksjs/docs` | [`stacks-docs`](../stacks-docs/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/docs/src/index.ts) | 2 |
 | `@stacksjs/email` | [`stacks-email`](../stacks-email/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/src/index.ts) | 23 |
 | `@stacksjs/enums` | [`stacks-enums`](../stacks-enums/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/enums/src/index.ts) | 3 |
-| `@stacksjs/env` | [`stacks-env`](../stacks-env/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/index.ts) | 30 |
+| `@stacksjs/env` | [`stacks-env`](../stacks-env/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/index.ts) | 31 |
 | `@stacksjs/error-handling` | [`stacks-error-handling`](../stacks-error-handling/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/error-handling/src/index.ts) | 10 |
 | `@stacksjs/events` | [`stacks-events`](../stacks-events/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/events/src/index.ts) | 12 |
 | `@stacksjs/faker` | [`stacks-faker`](../stacks-faker/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/faker/src/index.ts) | 1 |
@@ -68,14 +68,14 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@stacksjs/orm` | [`stacks-orm`](../stacks-orm/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/index.ts) | 73 |
 | `@stacksjs/pagination` | [`stacks-pagination`](../stacks-pagination/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/pagination/src/index.ts) | 0 |
 | `@stacksjs/path` | [`stacks-path`](../stacks-path/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/path/src/index.ts) | 13 |
-| `@stacksjs/payments` | [`stacks-payments`](../stacks-payments/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/index.ts) | 29 |
+| `@stacksjs/payments` | [`stacks-payments`](../stacks-payments/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/index.ts) | 30 |
 | `@stacksjs/push` | [`stacks-push`](../stacks-push/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/index.ts) | 6 |
 | `@stacksjs/query-builder` | [`stacks-query-builder`](../stacks-query-builder/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/query-builder/src/index.ts) | 6 |
 | `@stacksjs/queue` | [`stacks-queue`](../stacks-queue/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/queue/src/index.ts) | 49 |
 | `@stacksjs/realtime` | [`stacks-realtime`](../stacks-realtime/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/realtime/src/index.ts) | 12 |
 | `@stacksjs/registry` | [`stacks-registry`](../stacks-registry/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/registry/src/index.ts) | 1 |
 | `@stacksjs/repl` | [`stacks-repl`](../stacks-repl/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/repl/src/index.ts) | 2 |
-| `@stacksjs/router` | [`stacks-router`](../stacks-router/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/index.ts) | 96 |
+| `@stacksjs/router` | [`stacks-router`](../stacks-router/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/index.ts) | 97 |
 | `@stacksjs/scheduler` | [`stacks-scheduler`](../stacks-scheduler/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/scheduler/src/index.ts) | 14 |
 | `@stacksjs/search-engine` | [`stacks-search-engine`](../stacks-search-engine/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/search-engine/src/index.ts) | 11 |
 | `@stacksjs/security` | [`stacks-security`](../stacks-security/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/security/src/index.ts) | 11 |
@@ -119,7 +119,7 @@ Declared runtime exports: `BlogAdminError`, `DEFAULT_IOS_DEPENDENCIES`, `DEFAULT
 
 Local source modules: [src/action.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/action.ts), [src/add.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/add.ts), [src/blog-admin.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/blog-admin.ts), [src/build/ios-toolchain.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/build/ios-toolchain.ts), [src/commit.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/commit.ts), [src/dev/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/dev/index.ts), [src/discover-packages.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/discover-packages.ts), [src/generate/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/generate/index.ts), [src/github-release.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/github-release.ts), [src/helpers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/helpers/index.ts), [src/library/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/library/index.ts), [src/lint/lint.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/lint/lint.ts), [src/lint/stx-gate.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/lint/stx-gate.ts), [src/make-command.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/make-command.ts), [src/make-job.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/make-job.ts), [src/make-policy.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/make-policy.ts), [src/make-resource.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/make-resource.ts), [src/make.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/make.ts), [src/publication-preflight.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/publication-preflight.ts), [src/release-evidence.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/release-evidence.ts), [src/scaffold-crud.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/scaffold-crud.ts), [src/setup/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/setup/index.ts), [src/stacks.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/stacks.ts), [src/stx-source.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/stx-source.ts), [src/upgrade/package-project.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/upgrade/package-project.ts), [src/upgrade/route-actions.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/src/upgrade/route-actions.ts).
 
-Evidence directory: [89 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [91 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/actions/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/ai
 
@@ -127,9 +127,9 @@ Guidance: [`stacks-ai`](../stacks-ai/SKILL.md). Source: [storage/framework/core/
 
 Declared runtime exports: `assistantTurn`, `buildMessageWithImages`, `clearUsageReporters`, `estimateMessageTokens`, `estimateTokens`, `fetchWithRetry`, `listUsageReporters`, `normalizeMessagesForProvider`, `onUsage`, `recordUsage`, `sanitizePrompt`, `toolResultsTurn`.
 
-Local source modules: [src/agents/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/agents/index.ts), [src/buddy.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/buddy.ts), [src/client.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/client.ts), [src/context.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/context.ts), [src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/drivers/index.ts), [src/image.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/image.ts), [src/mcp-server.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/mcp-server.ts), [src/mcp.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/mcp.ts), [src/models.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/models.ts), [src/personalization.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/personalization.ts), [src/search.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/search.ts), [src/speech.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/speech.ts), [src/text.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/text.ts), [src/types.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/types.ts), [src/utils/client-bedrock-runtime.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/client-bedrock-runtime.ts), [src/utils/client-bedrock.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/client-bedrock.ts), [src/utils/model-access.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/model-access.ts), [src/utils/retry.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/retry.ts), [src/utils/tokens.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/tokens.ts), [src/utils/tools.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/tools.ts), [src/utils/usage.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/usage.ts), [src/utils/vision.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/vision.ts).
+Local source modules: [src/agents/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/agents/index.ts), [src/buddy.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/buddy.ts), [src/client.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/client.ts), [src/context.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/context.ts), [src/documents.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/documents.ts), [src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/drivers/index.ts), [src/image.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/image.ts), [src/mcp-server.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/mcp-server.ts), [src/mcp.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/mcp.ts), [src/models.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/models.ts), [src/personalization.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/personalization.ts), [src/search.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/search.ts), [src/speech.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/speech.ts), [src/text.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/text.ts), [src/types.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/types.ts), [src/utils/client-bedrock-runtime.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/client-bedrock-runtime.ts), [src/utils/client-bedrock.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/client-bedrock.ts), [src/utils/model-access.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/model-access.ts), [src/utils/retry.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/retry.ts), [src/utils/tokens.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/tokens.ts), [src/utils/tools.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/tools.ts), [src/utils/usage.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/usage.ts), [src/utils/vision.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/src/utils/vision.ts).
 
-Evidence directory: [17 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [18 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/ai/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/alias
 
@@ -217,7 +217,7 @@ Read the entrypoint and package export map for re-exported or type-only surfaces
 
 Local source modules: [src/commands/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/src/commands/index.ts).
 
-Evidence directory: [169 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [170 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/build
 
@@ -443,9 +443,9 @@ Guidance: [`stacks-env`](../stacks-env/SKILL.md). Source: [storage/framework/cor
 
 Read the entrypoint and package export map for re-exported or type-only surfaces.
 
-Local source modules: [src/cli.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/cli.ts), [src/crypto.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/crypto.ts), [src/deployment.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/deployment.ts), [src/integrations.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/integrations.ts), [src/numeric-keys.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/numeric-keys.ts), [src/parser.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/parser.ts), [src/plaintext.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/plaintext.ts), [src/plugin.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/plugin.ts), [src/runtime.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/runtime.ts), [src/tenants.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/tenants.ts), [src/types.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/types.ts), [src/utils.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/utils.ts).
+Local source modules: [src/cli.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/cli.ts), [src/crypto.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/crypto.ts), [src/deployment.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/deployment.ts), [src/integrations.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/integrations.ts), [src/numeric-keys.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/numeric-keys.ts), [src/parser.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/parser.ts), [src/plaintext.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/plaintext.ts), [src/plugin.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/plugin.ts), [src/runtime.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/runtime.ts), [src/tenants.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/tenants.ts), [src/types.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/types.ts), [src/utils.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/utils.ts), [src/withheld.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/src/withheld.ts).
 
-Evidence directory: [30 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [31 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/env/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/error-handling
 
@@ -661,7 +661,7 @@ Declared runtime exports: `Payment`, `freshIdempotencyKey`, `stacksIdempotencyKe
 
 Local source modules: [src/billable/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/billable/index.ts), [src/checkout-outcome.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/checkout-outcome.ts), [src/connect/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/connect/index.ts), [src/direct-debit.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/direct-debit.ts), [src/driver/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/driver/index.ts), [src/drivers/stripe.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/drivers/stripe.ts), [src/idempotency.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/idempotency.ts), [src/payment.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/payment.ts), [src/subscription-state.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/subscription-state.ts), [src/terminal.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/terminal.ts).
 
-Evidence directory: [29 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [30 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/push
 
@@ -721,11 +721,11 @@ Evidence directory: [2 retained tests](https://github.com/stacksjs/stacks/blob/m
 
 Guidance: [`stacks-router`](../stacks-router/SKILL.md). Source: [storage/framework/core/router/src/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/index.ts).
 
-Declared runtime exports: `DASHBOARD_ROUTE_GROUPS`, `DEFAULT_ROUTE_BUNDLE_FEATURES`, `DEFAULT_ROUTE_REGISTRY`, `DatabaseSessionStore`, `EncryptedSessionStore`, `FileSessionStore`, `JSON_CONTENT_TYPE`, `MemorySessionStore`, `Middleware`, `PathParamError`, `RedisSessionStore`, `RequestBodyError`, `appRouteRegistry`, `assertRouteMiddlewareResolvable`, `bundleMounts`, `cacheRedisConnection`, `cacheRequestQuery`, `checkApplicationHealth`, `clearCsrfModuleCache`, `clearCurrentRequest`, `clearMiddlewareCache`, `clearRateLimit`, `clearRouteModelBindings`, `clearTrackedQueries`, `clientAddress`, `configureViewDirectories`, `createErrorResponse`, `createMiddlewareErrorResponse`, `createNotFoundResponse`, `createSessionStore`, `createStacksRouter`, `createStacksSessionStore`, `createTypedRouter`, `createValidationErrorResponse`, `dashboardGroupMiddleware`, `defineMiddleware`, `defineRouteModelBinding`, `describeUnknownDashboardGroups`, `disableViewRouting`, `enhanceRequest`, `fallbackStorage`, `findUnresolvableRouteMiddleware`, `getCurrentRequest`, `getQueryShapeCounts`, `getTraceId`, `installMiddlewareHotReload`, `isApiRequest`, `isRouterAction`, `listNamedRoutes`, `listRedirectRoutes`, `listRegisteredRoutes`, `listRootMountedAppRoutes`, `loadMiddlewareHandlers`, `loadRoutes`, `mountedDefaultRouteBundles`, `parseJsonText`, `rateLimit`, `rateLimitScale`, `rateLimitStatus`, `readJsonBody`, `readTextBody`, `request`, `resetBootHooks`, `resetRateLimiters`, `resetSharedRateLimitStorage`, `resolveDashboardAccess`, `resolveRouteModel`, `route`, `routeModelBindings`, `routeParams`, `runBootHooks`, `runHealthProbes`, `runWithRequest`, `safePathParam`, `sanitizePathParam`, `scaledLimit`, `serve`, `serverResponse`, `setCurrentRequest`, `setRouteModelFallback`, `sharedRateLimitStorage`, `signUrl`, `signedUrl`, `stream`, `trackQuery`, `trustedProxies`, `url`, `useRateLimitStorage`, `verifySignedUrl`, `verifySignedUrlMiddleware`, `warnOnMultipleRouterInstances`, `withRouteAdmission`, `withTraceId`, `wrapAction`.
+Declared runtime exports: `DASHBOARD_ROUTE_GROUPS`, `DEFAULT_ROUTE_BUNDLE_FEATURES`, `DEFAULT_ROUTE_REGISTRY`, `DatabaseSessionStore`, `EncryptedSessionStore`, `FileSessionStore`, `JSON_CONTENT_TYPE`, `MemorySessionStore`, `Middleware`, `PathParamError`, `RedisSessionStore`, `RequestBodyError`, `appRouteRegistry`, `assertRouteMiddlewareResolvable`, `bundleMounts`, `cacheRedisConnection`, `cacheRequestQuery`, `checkApplicationHealth`, `clearCsrfModuleCache`, `clearCurrentRequest`, `clearMiddlewareCache`, `clearRateLimit`, `clearRouteModelBindings`, `clearTrackedQueries`, `clientAddress`, `configureViewDirectories`, `createErrorResponse`, `createMiddlewareErrorResponse`, `createNotFoundResponse`, `createSessionStore`, `createStacksRouter`, `createStacksSessionStore`, `createTypedRouter`, `createValidationErrorResponse`, `dashboardGroupMiddleware`, `defineMiddleware`, `defineRouteModelBinding`, `describeUnknownDashboardGroups`, `disableViewRouting`, `enhanceRequest`, `fallbackStorage`, `findUnresolvableRouteMiddleware`, `getCurrentRequest`, `getQueryShapeCounts`, `getTraceId`, `installMiddlewareHotReload`, `isApiRequest`, `isRouterAction`, `listNamedRoutes`, `listRedirectRoutes`, `listRegisteredRoutes`, `listRootMountedAppRoutes`, `loadMiddlewareHandlers`, `loadRoutes`, `mountedDefaultRouteBundles`, `parseJsonText`, `rateLimit`, `rateLimitScale`, `rateLimitStatus`, `readJsonBody`, `readTextBody`, `request`, `resetBootHooks`, `resetRateLimiters`, `resetSharedRateLimitStorage`, `resetShutdownHooks`, `resolveDashboardAccess`, `resolveRouteModel`, `route`, `routeModelBindings`, `routeParams`, `runBootHooks`, `runHealthProbes`, `runShutdownHooks`, `runWithRequest`, `safePathParam`, `sanitizePathParam`, `scaledLimit`, `serve`, `serverResponse`, `setCurrentRequest`, `setRouteModelFallback`, `sharedRateLimitStorage`, `signUrl`, `signedUrl`, `stream`, `trackQuery`, `trustedProxies`, `url`, `useRateLimitStorage`, `verifySignedUrl`, `verifySignedUrlMiddleware`, `warnOnMultipleRouterInstances`, `withRouteAdmission`, `withTraceId`, `wrapAction`.
 
 Local source modules: [src/api-shape.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/api-shape.ts), [src/body.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/body.ts), [src/dashboard-access.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/dashboard-access.ts), [src/encrypted-session-store.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/encrypted-session-store.ts), [src/error-handler.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/error-handler.ts), [src/health.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/health.ts), [src/json.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/json.ts), [src/middleware.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/middleware.ts), [src/path-sanitize.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/path-sanitize.ts), [src/rate-limit.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/rate-limit.ts), [src/request-augmentation.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/request-augmentation.ts), [src/request-context.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/request-context.ts), [src/route-loader.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/route-loader.ts), [src/route-model-binding.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/route-model-binding.ts), [src/security-settings.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/security-settings.ts), [src/session-factory.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/session-factory.ts), [src/signed-url.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/signed-url.ts), [src/stacks-router.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/stacks-router.ts), [src/typed-router.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/typed-router.ts).
 
-Evidence directory: [96 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [97 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/scheduler
 

package/ai/skills/stacks-router/SKILL.md

@@ -417,6 +417,31 @@ await serve({ port: 3000 })
 const response = await serverResponse(request)
 ```
 
+### Boot and shutdown hooks
+
+```typescript
+import { route } from '@stacksjs/router'
+
+// Once, after the routes load and before the first request. Optional
+// preparation only: a hook that throws is logged and the boot continues.
+route.booting('warm grammars', () => highlighter.load())
+
+// When the server is told to stop. For whatever would otherwise outlive the
+// process or end unrecorded: open sessions, child processes, a buffer to flush.
+route.stopping('terminal sessions', () => terminalSessions.closeAll())
+```
+
+- Boot hooks run in order, once per process, from `serve()`.
+- Shutdown hooks run concurrently, once per process (a second signal waits on
+  the same run). One that throws is logged and the rest still run.
+- The production API server (`core/actions/src/serve/api.ts`) runs them on
+  SIGTERM alongside draining in-flight requests. `SHUTDOWN_GRACE_MS` (default
+  fifteen seconds) caps both, so a hook that hangs cannot hold the process.
+- The list lives on `globalThis`, so a module registering through a second copy
+  of `@stacksjs/router` still reaches the one the server runs.
+- `buddy dev:api` has no shutdown handler: Ctrl-C ends the process group, and
+  shutdown hooks do not run there.
+
 ## URL Generation
 
 ```typescript

package/app/Actions/Dashboard/Remote/remote-terminal.test.ts

@@ -1,13 +1,14 @@
 import type { UserModel } from '@stacksjs/orm'
 import type { RemoteHost } from './remote-commands'
 import type { TerminalAuditSink, TerminalEvent, TerminalProcess, TerminalSessionOptions } from './remote-terminal'
-import { describe, expect, it } from 'bun:test'
-import { existsSync, readdirSync } from 'node:fs'
+import { describe, expect, it, jest } from 'bun:test'
+import { existsSync } from 'node:fs'
 import { tmpdir } from 'node:os'
+import { dirname } from 'node:path'
 import { sshTerminalArgv } from './remote-commands'
 import { TerminalSessions } from './remote-terminal'
 import { createPtySpawner } from './ssh-runner'
-import { encodeTerminalEvent, terminalEventStream } from './terminal-sessions'
+import { encodeTerminalEvent, terminalEventStream, terminalSessions } from './terminal-sessions'
 
 /**
  * Interactive terminal sessions (stacksjs/stacks#960). Every rule is asserted
@@ -236,16 +237,28 @@ describe('a session does not outlive its purpose', () => {
   })
 
   it('input keeps it alive; the max duration ends it regardless', async () => {
-    const { manager, fakes, audit } = sessions({ idleTimeoutMs: 40, maxDurationMs: 120, detachGraceMs: 10_000 })
-    const { id } = await manager.open({ user: alice, hosts, hostKey: 'app', authorizer: allowAll, cols: 80, rows: 24 })
-    for (let i = 0; i < 4; i++) {
-      await Bun.sleep(25)
-      await manager.input(id, alice, 'x')
+    // The clock is driven, not slept on: the deadlines under test run on the
+    // same clock a sleep waits on, so under load a sleep overshot them (#2978).
+    jest.useFakeTimers()
+    try {
+      const { manager, fakes, audit } = sessions({ idleTimeoutMs: 40, maxDurationMs: 120, detachGraceMs: 10_000 })
+      const { id } = await manager.open({ user: alice, hosts, hostKey: 'app', authorizer: allowAll, cols: 80, rows: 24 })
+      for (let i = 0; i < 4; i++) {
+        jest.advanceTimersByTime(25)
+        await manager.input(id, alice, 'x')
+      }
+      const ending = take(manager.watch(id, alice), 1)
+      // 119ms in: more than twice the idle timeout, kept open by the input.
+      jest.advanceTimersByTime(19)
+      expect(fakes[0]!.killed).toBe(false)
+      jest.advanceTimersByTime(1)
+      expect(fakes[0]!.killed).toBe(true)
+      expect((await ending).map(text)).toEqual(['<max-duration>'])
+      expect(audit.log.at(-1)).toStartWith('closed max-duration')
+    }
+    finally {
+      jest.useRealTimers()
     }
-    expect(fakes[0]!.killed).toBe(false)
-    await Bun.sleep(60)
-    expect(fakes[0]!.killed).toBe(true)
-    expect(audit.log.at(-1)).toStartWith('closed max-duration')
   })
 
   it('ends when nobody attaches, and a grace period after the last viewer leaves', async () => {
@@ -272,6 +285,40 @@ describe('a session does not outlive its purpose', () => {
     await expect(manager.close(id, alice)).rejects.toThrow('No such terminal session')
     expect(audit.log.slice(1)).toEqual(['input rm -rf /tmp/build', 'closed closed in=17 out=0'])
   })
+
+  it('shuts down only once every process has exited, so nothing it made outlives it', async () => {
+    // The real spawner removes its temp directory when the process exits; a
+    // shutdown that returned on the kill raced the process exiting (#2978).
+    let exit!: (code: number) => void
+    const { manager } = sessions({
+      spawn: () => ({ write: () => {}, resize: () => {}, kill: () => {}, exited: new Promise<number>((resolve) => { exit = resolve }) }),
+    })
+    await manager.open({ user: alice, hosts, hostKey: 'app', authorizer: allowAll, cols: 80, rows: 24 })
+
+    const closing = manager.closeAll().then(() => 'closed')
+    expect(await Promise.race([closing, Bun.sleep(20).then(() => 'waiting')])).toBe('waiting')
+    exit(-1)
+    expect(await closing).toBe('closed')
+  })
+
+  it('is closed by the server stopping, through the router\'s shutdown hooks (#3034)', async () => {
+    const registered = (globalThis as Record<symbol, { hooks: Array<{ name: string, run: () => unknown }> }>)[Symbol.for('@stacksjs/router:shutdown-hooks')]
+    const hook = registered?.hooks.find(entry => entry.name === 'terminal sessions')
+    expect(hook).toBeDefined()
+
+    // The app's own sessions, not a copy: the hook has to reach the manager
+    // the terminal actions open sessions on.
+    const closeAll = terminalSessions.closeAll
+    let closed = 0
+    terminalSessions.closeAll = async () => { closed += 1 }
+    try {
+      await hook!.run()
+    }
+    finally {
+      terminalSessions.closeAll = closeAll
+    }
+    expect(closed).toBe(1)
+  })
 })
 
 describe('the event stream', () => {
@@ -304,7 +351,6 @@ describe('the PTY spawner', () => {
   })
 
   it('carries output, input and a window resize through a real PTY, and cleans up', async () => {
-    const before = readdirSync(tmpdir()).filter(name => name.startsWith('stacks-terminal-')).length
     let knownHosts = ''
     const spawn = createPtySpawner((_host, path) => {
       knownHosts = path
@@ -315,7 +361,10 @@ describe('the PTY spawner', () => {
     const process = await spawn(shellHost, { cols: 100, rows: 30 }, (bytes) => { output += new TextDecoder().decode(bytes) })
     expect(existsSync(knownHosts)).toBe(true)
 
-    await Bun.sleep(150)
+    // Resize once the shell has reported the size it started at, not after a
+    // guess at how long that takes.
+    for (let i = 0; i < 200 && !output.includes('30 100'); i++)
+      await Bun.sleep(10)
     process.resize(132, 40)
     process.write('hello\r')
     expect(await process.exited).toBe(0)
@@ -324,8 +373,9 @@ describe('the PTY spawner', () => {
     expect(output).toContain('30 100')
     expect(output).toContain('40 132')
     expect(output).toContain('got:hello')
-    expect(existsSync(knownHosts)).toBe(false)
-    expect(readdirSync(tmpdir()).filter(name => name.startsWith('stacks-terminal-')).length).toBe(before)
+    // The directory this spawn created, not a count of the shared temp
+    // directory, which other processes change underneath the test (#2978).
+    expect(existsSync(dirname(knownHosts))).toBe(false)
   })
 })
 

package/app/Actions/Dashboard/Remote/remote-terminal.ts

@@ -261,9 +261,15 @@ export class TerminalSessions {
     await this.end(this.find(id, user), 'closed')
   }
 
-  /** End every session, for a server shutting down. */
+  /**
+   * End every session, for a server shutting down, and wait for each process
+   * to exit: the spawner cleans up after the process, and a server that exits
+   * first leaves that behind.
+   */
   async closeAll(): Promise<void> {
-    await Promise.all([...this.sessions.values()].map(session => this.end(session, 'shutdown')))
+    const open = [...this.sessions.values()]
+    await Promise.all(open.map(session => this.end(session, 'shutdown')))
+    await Promise.all(open.map(session => session.process.exited))
   }
 
   /**

package/app/Actions/Dashboard/Remote/terminal-sessions.ts

@@ -1,5 +1,6 @@
 import type { TerminalAuthorizer, TerminalEvent } from './remote-terminal'
 import { Gate } from '@stacksjs/auth'
+import { route } from '@stacksjs/router'
 import { TerminalSessions } from './remote-terminal'
 import { createPtySpawner, loggingTerminalAuditSink } from './ssh-runner'
 
@@ -18,6 +19,10 @@ export const terminalSessions: TerminalSessions = new TerminalSessions({
   audit: loggingTerminalAuditSink,
 })
 
+// A server that stops closes its sessions first, so each one records why it
+// ended and its temp directory goes with its process (stacksjs/stacks#3034).
+route.stopping('terminal sessions', () => terminalSessions.closeAll())
+
 /**
  * The `open-remote-terminal` gate, or undefined when the app has not defined
  * it - and `TerminalSessions.open` refuses in that case rather than proceeding.

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.336",
+  "version": "0.75.339",
   "description": "Stacks, built into VS Code: stx templates, pickier linting and formatting, encrypted env files, the dev server preview and every buddy command. No other extensions required.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.336",
+  "version": "0.75.339",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -45,7 +45,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "0.75.336",
+    "@stacksjs/mobile": "0.75.339",
     "@stacksjs/sanitizer": "0.2.736",
     "@stacksjs/stx": "0.2.736",
     "@xterm/addon-fit": "^0.11.0",

package/resources/components/Dashboard/Auth/AccessTokens.stx

@@ -221,7 +221,7 @@ onMount(() => {
       <span class="h-4 w-4 i-hugeicons-key-02"></span>
       Create Token
     </Button>
-    <Button :if="!loading() && authenticationRequired()" tag="a" href="/login">
+    <Button :if="!loading() && authenticationRequired()" tag="a" href="/login?redirect=/access-tokens">
       <span class="h-4 w-4 i-hugeicons-login-03"></span>
       Sign in
     </Button>
@@ -271,7 +271,7 @@ onMount(() => {
       description="Personal access tokens belong to an authenticated account. Sign in to create, inspect, or revoke them."
     >
       <template #action>
-        <Button tag="a" href="/login">
+        <Button tag="a" href="/login?redirect=/access-tokens">
           <span class="h-4 w-4 i-hugeicons-login-03"></span>
           Sign in
         </Button>

package/resources/components/Dashboard/Remote/RemoteConsole.stx

@@ -1,5 +1,6 @@
 <script client>
 import type { RemoteCommandResult, RemoteRegistry } from '../../../../functions/remote'
+import { DashboardApiError } from '../../../../functions/dashboard-api'
 import { fetchRemoteRegistry, requestRemoteCommand } from '../../../../functions/remote'
 import { registerRemoteTerminal } from '../../../../functions/remote-terminal-element'
 import { pushToast } from '../../../../functions/toasts'
@@ -9,6 +10,9 @@ void registerRemoteTerminal()
 const registry = state<RemoteRegistry | null>(null)
 const isLoading = state(true)
 const loadError = state('')
+// Remote access needs a signed-in account even where the rest of the dev
+// dashboard does not, so a 401 here asks for a sign-in rather than failing.
+const authenticationRequired = state(false)
 const selectedHost = state('')
 const selectedCommand = state('')
 const isRunning = state(false)
@@ -27,6 +31,7 @@ const commandsForHost = derived(() => {
 async function load(): Promise<void> {
   isLoading.set(true)
   loadError.set('')
+  authenticationRequired.set(false)
   try {
     const data = await fetchRemoteRegistry()
     registry.set(data)
@@ -34,7 +39,10 @@ async function load(): Promise<void> {
       selectedHost.set(data.hosts[0].key)
   }
   catch (error) {
-    loadError.set(error instanceof Error ? error.message : 'The remote hosts could not be loaded.')
+    if (error instanceof DashboardApiError && error.status === 401)
+      authenticationRequired.set(true)
+    else
+      loadError.set(error instanceof Error ? error.message : 'The remote hosts could not be loaded.')
   }
   finally {
     isLoading.set(false)
@@ -87,6 +95,20 @@ onMount(() => {
 
   <div :if="isLoading()" class="text-gray-500 text-sm dark:text-neutral-400">Loading hosts</div>
 
+  <EmptyState
+    :if="!isLoading() && authenticationRequired()"
+    icon="i-hugeicons-user-lock-01"
+    title="Sign in to use remote access"
+    description="Running commands and opening terminals on your servers needs a signed-in account, in every environment. Each run and session is recorded under it."
+  >
+    <template #action>
+      <Button tag="a" href="/login?redirect=/remote">
+        <span class="h-4 w-4 i-hugeicons-login-03"></span>
+        Sign in
+      </Button>
+    </template>
+  </EmptyState>
+
   <section :if="!isLoading() && registry() && hosts().length === 0" class="p-6 bg-white dark:bg-neutral-800 border border-gray-200 rounded-lg dark:border-neutral-700">
     <h2 class="font-semibold text-gray-900 dark:text-white">No hosts are configured</h2>
     <p class="mt-1 max-w-2xl text-gray-500 text-sm dark:text-neutral-400">