Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 32 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,19 @@ All notable user-visible changes are recorded here. Versions follow [Semantic Ve
`blog/posts/`, and the build renders the index, each post, an RSS feed and a
sitemap as static pages. See blog/README.md.
- `/blogs` and `/blogs/<post>/` redirect to the same page under `/blog/`.
- A one-screen landing page at `/start/` for paid traffic, to test against
the home page. It says what shell does in one line and gives the three
setup steps: install, start your agent (`shell claude`, or tap Codex,
Hermes, OpenCode or Cursor), and scan the QR code. On a phone, "Send these
steps to my laptop" opens the share sheet. The page gets the home page's
analytics and X pixel, is kept out of search results, and reports as its
own route (`start`, `landing_start` on the statistics dashboard).
- Ad-specific versions of `/start/`, set up in PostHog without a deploy. An ad
links to `/start/?utm_content=<page>`, and the page takes that page's
headline, subline, step 2 agent and button text from the payload of the
`start-landing-pages` feature flag. An unknown page, or PostHog being slow or
blocked, shows the default page. Events from the visit record the page key
as `landing_variant`, so results can be compared page by page.
- The installer runs a `shell` command once it has installed, by the new
executable's full path, so one pasted line can install and link a machine
before its install directory is on PATH:
Expand Down Expand Up @@ -51,6 +64,25 @@ All notable user-visible changes are recorded here. Versions follow [Semantic Ve
- Answers that resume after an idle pause continue in the same chat message.
- Blue “Reading … as messages” notices are restored. Summary permission switches
reflect a successful save immediately instead of waiting for the next poll.
- `npm run deploy:production` refuses a config that does not set
`POSTHOG_ENABLED` to `"0"` or `"1"`. Since 0.23.1 the relay has been
deployed with a config that left the flag out, and because Wrangler replaces
every Worker variable on deploy, relay analytics (downloads, installs,
sessions, viewers and MCP results) silently stopped on 23 September. The
accounts app was unaffected because its flag is committed. Production needs
`"POSTHOG_ENABLED": "1"` in `wrangler.production.jsonc` and a redeploy to
restore it.
- Starting `claude` (or `opencode`) from the app no longer reopens an old
agent conversation. Any `shell` command starts the background daemon when
none is running, and it passed on its whole environment. Run from inside
Claude Code, that included the conversation's id, so every session the app
then asked for was treated as a handoff and forked that conversation instead
of starting fresh, until the daemon restarted. The daemon and the sessions it
starts no longer carry an agent conversation's identity, and a session the
app asks for never hands off. Typing `shell claude` inside Claude Code still
forks the conversation, as before. Machines already affected are fixed once
the new release's daemon replaces the running one (`shell service install`,
a restart, or signing in again).
- Signing in from the header link of the sign-up page returns to the terminal
link request that sent you there. It used to land on the sessions list, with
the terminal still waiting for a callback that was never coming.
Expand Down Expand Up @@ -194,7 +226,6 @@ All notable user-visible changes are recorded here. Versions follow [Semantic Ve
- Shell Keep's "Gather now" answered "internal error". The database only
allowed a command to be a start or a kill, while the rest of the system
already accepted the gathering's probe.

## [0.23.3] — 2026-09-25

### Fixed
Expand Down
6 changes: 5 additions & 1 deletion cmd/shell/agent_loop.go
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,11 @@ func performAgentCommand(
// not silently weaken E2EE or widen file sharing on the wrapper itself.
arguments := append([]string{"--"}, browserCommandArguments(command.Command)...)
launch := exec.CommandContext(ctx, self, arguments...)
launch.Env = passwordHandoffEnvironment(os.Environ(), "")
// Never an agent conversation's identity, even from a daemon an older
// release started with one: the browser asked for a new program. Also
// drop any inherited browser password the parent was handed, as a
// fresh launch reads its own from the pipe or not at all.
launch.Env = passwordHandoffEnvironment(detachedEnvironment(os.Environ()), "")
if command.Name != "" {
// The launched shell reads this when it publishes the session, so
// the name chosen in the browser survives to the session list.
Expand Down
2 changes: 1 addition & 1 deletion cmd/shell/daemon_unix.go
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ func startDetachedDaemon(self string) {
defer null.Close()

command := exec.Command(self, "daemon")
command.Env = os.Environ()
command.Env = detachedEnvironment(os.Environ())
command.Stdin = null
command.Stdout = null
command.Stderr = null
Expand Down
2 changes: 1 addition & 1 deletion cmd/shell/daemon_windows.go
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ func startDetachedDaemon(self string) {
defer null.Close()

command := exec.Command(self, "daemon")
command.Env = os.Environ()
command.Env = detachedEnvironment(os.Environ())
command.Stdin = null
command.Stdout = null
command.Stderr = null
Expand Down
37 changes: 37 additions & 0 deletions cmd/shell/handoff.go
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,43 @@ func prepareCommandLaunch(arguments, environment []string, allowHandoff bool) co
return launch
}

// harnessIdentityVariables are the variables an agent harness sets to tell a
// tool subprocess which conversation it belongs to. They are right for the one
// command the agent ran, and wrong for anything that outlives it.
//
// The daemon is the case that matters: any shell command starts it when none
// is running, so a first command typed inside Claude Code used to leave a
// daemon carrying that conversation's id. Every session the browser then asked
// for inherited it, read as a handoff, and forked that old conversation instead
// of starting the program that was asked for, until the daemon next restarted.
//
// Keep this a superset of every adapter's detection and strip lists;
// TestHarnessIdentityVariablesCoverEveryAdapter checks.
var harnessIdentityVariables = []string{
"CLAUDECODE",
"CLAUDE_CODE_CHILD_SESSION",
"CLAUDE_CODE_SESSION_ID",
"CLAUDE_CODE_BRIDGE_SESSION_ID",
"CLAUDE_CODE_REMOTE_SESSION_ID",
"OPENCODE",
"OPENCODE_PID",
"OPENCODE_SESSION_ID",
"AGENT",
}

// detachedEnvironment is the environment for a process that outlives the
// command that started it: this one, minus any agent conversation's identity.
func detachedEnvironment(environment []string) []string {
return removeEnvironmentVariables(environment, harnessIdentityVariables...)
}

// handoffAllowed reports whether a launch may fork the agent conversation it
// was started from. Only a background launch someone typed may. A session the
// browser asked for never does: it asked for the program, started fresh.
func handoffAllowed(foreground bool, environment []string) bool {
return !foreground && environmentValue(environment, sessionOriginEnvironment) == ""
}

func environmentValue(environment []string, name string) string {
prefix := name + "="
for _, entry := range environment {
Expand Down
67 changes: 67 additions & 0 deletions cmd/shell/handoff_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -233,3 +233,70 @@ func TestOpencodeAdapterFallsBackToContinueWhenUnresolvable(t *testing.T) {
t.Fatalf("arguments = %#v, want %#v", launch.Arguments, wantArguments)
}
}

func TestHarnessIdentityVariablesCoverEveryAdapter(t *testing.T) {
listed := map[string]bool{}
for _, name := range harnessIdentityVariables {
listed[name] = true
}
for _, adapter := range harnessAdapters {
// With a session id, every adapter rewrites without touching disk.
_, stripped, _ := adapter.Rewrite(adapter.Binary, testClaudeSessionID)
for _, name := range stripped {
if !listed[name] {
t.Errorf("%s strips %s, which harnessIdentityVariables does not list", adapter.Binary, name)
}
}
}
for _, name := range []string{"CLAUDE_CODE_CHILD_SESSION", "CLAUDE_CODE_SESSION_ID", "OPENCODE", "OPENCODE_SESSION_ID"} {
if !listed[name] {
t.Errorf("harnessIdentityVariables does not list detection variable %s", name)
}
}
}

func TestDetachedEnvironmentDropsAgentConversationIdentity(t *testing.T) {
got := detachedEnvironment([]string{
"PATH=/usr/bin",
"CLAUDECODE=1",
"CLAUDE_CODE_CHILD_SESSION=1",
"CLAUDE_CODE_SESSION_ID=" + testClaudeSessionID,
"OPENCODE=1",
"OPENCODE_SESSION_ID=" + testOpencodeSessionID,
"HOME=/home/someone",
"SHELL_ONLINE_CONFIG=/tmp/config.json",
})
want := []string{"PATH=/usr/bin", "HOME=/home/someone", "SHELL_ONLINE_CONFIG=/tmp/config.json"}
if !reflect.DeepEqual(got, want) {
t.Fatalf("detachedEnvironment = %#v, want %#v", got, want)
}
}

// Regression: a daemon first started from inside a Claude Code conversation
// passed that conversation's id to every browser-started session, so starting
// `claude` from the app forked that old conversation again, every time.
func TestBrowserStartedSessionNeverForksAnAgentConversation(t *testing.T) {
inherited := []string{
"CLAUDECODE=1",
"CLAUDE_CODE_CHILD_SESSION=1",
"CLAUDE_CODE_SESSION_ID=" + testClaudeSessionID,
sessionOriginEnvironment + "=cmd_123",
}
// Even if the variables reach the session, the browser's request is not a handoff.
launch := prepareCommandLaunch([]string{"claude"}, inherited, handoffAllowed(false, inherited))
if launch.Handoff != "" || !reflect.DeepEqual(launch.Arguments, []string{"claude"}) {
t.Fatalf("browser-started claude handed off: %#v", launch)
}
// And they no longer reach it: the daemon and its sessions start without them.
if value := environmentValue(detachedEnvironment(inherited), "CLAUDE_CODE_SESSION_ID"); value != "" {
t.Fatalf("detached environment kept the conversation id %q", value)
}
// Typed inside Claude Code, `shell claude` still forks the conversation, as before.
typed := inherited[:3]
if launch := prepareCommandLaunch([]string{"claude"}, typed, handoffAllowed(false, typed)); launch.Handoff != claudeConversationHandoff {
t.Fatalf("typed shell claude no longer hands off: %#v", launch)
}
if handoffAllowed(true, typed) {
t.Fatal("a foreground launch must not hand off")
}
}
2 changes: 1 addition & 1 deletion cmd/shell/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@ func run(arguments []string, stdout, stderr io.Writer) int {
if len(command) == 0 {
command = []string{defaultShellCommand()}
}
launch := prepareCommandLaunch(command, os.Environ(), !*foreground)
launch := prepareCommandLaunch(command, os.Environ(), handoffAllowed(*foreground, os.Environ()))
command = launch.Arguments
fileService, err := openSharedFileService(*shareFiles, *filesRoot)
if err != nil {
Expand Down
5 changes: 4 additions & 1 deletion docs/self-hosting.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,10 @@ Objects, Rate Limiting, Analytics Engine, and static assets. Keep every
documentation path in `run_worker_first`: a page served straight from the
assets binding is never counted. `npm run deploy:production` refuses a
production config that routes fewer of these paths through the Worker than
`wrangler.example.jsonc` does.
`wrangler.example.jsonc` does, or one that does not set `POSTHOG_ENABLED` to
`"0"` or `"1"`. Wrangler replaces every Worker variable on deploy, so a config
that leaves the flag out turns relay analytics off without any error. The
example keeps it `"0"`; a self-hosted relay sends nothing to PostHog.

The private statistics dashboard is optional and configured with Worker
secrets (`npx wrangler secret put <NAME>`):
Expand Down
6 changes: 6 additions & 0 deletions scripts/deploy-production.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,12 @@ export function validateProductionConfig(config) {
!["0", "1"].includes(config.vars?.MCP_CONTROL_ENABLED)) {
throw new Error("production target, pinned account, or explicit control gate is invalid");
}
// Wrangler replaces every Worker var on deploy. A config that omits the flag
// silently turns relay analytics off (installs, sessions, viewers, MCP), so
// the choice must be written down, the same way as the control gate.
if (!["0", "1"].includes(config.vars?.POSTHOG_ENABLED)) {
throw new Error("production config must set vars.POSTHOG_ENABLED to \"0\" or \"1\"");
}
}

export function deployProduction({ argv = [], configPath = resolve("wrangler.production.jsonc"), executor } = {}) {
Expand Down
4 changes: 3 additions & 1 deletion scripts/test-install-windows.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,10 @@ try {
Set-Content -NoNewline -Path (Join-Path $downloads "SHA256SUMS") -Value "$digest $artifact`n"

$server = Start-Process python -ArgumentList "-m", "http.server", "18787", "--bind", "127.0.0.1", "--directory", $root -PassThru -WindowStyle Hidden
$deadline = [DateTime]::UtcNow.AddSeconds(10)
# A cold hosted runner can take well over ten seconds to start Python.
$deadline = [DateTime]::UtcNow.AddSeconds(60)
do {
if ($server.HasExited) { throw "The test download server (python -m http.server) exited with code $($server.ExitCode)" }
try {
Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:18787/downloads/SHA256SUMS" | Out-Null
break
Expand Down
4 changes: 3 additions & 1 deletion scripts/test-terminal-live-browser.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -731,7 +731,9 @@ try {
if (runtime) { try { process.kill(-runtime.pid, "SIGTERM"); } catch {} await delay(300); }
try { await transport?.close(); } catch {}
try { await vite?.close(); } catch {}
rmSync(temp, { recursive: true, force: true });
// Chrome may still be writing its profile here as it exits, which made this
// throw ENOTEMPTY after every check had passed. Node retries exactly that.
rmSync(temp, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
}
process.exitCode = failed ? 1 : 0;

Expand Down
10 changes: 10 additions & 0 deletions shared/landing-paths.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
/**
* The public landing pages. "/" is the home page; "/start/" is a one-screen
* page for paid traffic, tested against it. Both get the landing page's
* analytics, X pixel and Content-Security-Policy, and nothing else does.
*/
export const START_PATH = "/start/";

export function isLandingPath(pathname: string): boolean {
return pathname === "/" || pathname === "" || pathname === START_PATH;
}
10 changes: 7 additions & 3 deletions shared/posthog.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ const EVENTS = new Set([
]);
const VALUES: Record<string, ReadonlySet<string>> = {
surface: new Set(["landing", "docs", "terminal", "app", "game", "relay"]),
route: new Set(["landing", "docs", "terminal", "login", "signup", "reset", "feedback", "account", "sessions", "session", "audit", "team", "join", "terms", "privacy", "machines", "game", "cli_authorize"]),
target: new Set(["install", "brew_install", "source_build", "run", "docs_command", "share", "skill", "start_nav", "start_hero", "start_footer", "start_bottom", "demo", "github_star", "signup_nav", "signup_hero", "signup_team", "signup_footer", "github", "signup", "signin", "docs", "app", "feedback", "session", "machine", "team", "vault", "automation", "account", "command", "invite", "cli", "unknown"]),
route: new Set(["landing", "start", "docs", "terminal", "login", "signup", "reset", "feedback", "account", "sessions", "session", "audit", "team", "join", "terms", "privacy", "machines", "game", "cli_authorize"]),
target: new Set(["install", "brew_install", "source_build", "run", "docs_command", "share", "skill", "start_nav", "start_hero", "start_footer", "start_bottom", "start_share", "demo", "github_star", "signup_nav", "signup_hero", "signup_team", "signup_footer", "github", "signup", "signin", "docs", "app", "feedback", "session", "machine", "team", "vault", "automation", "account", "command", "invite", "cli", "unknown"]),
source: new Set(["x", "google", "github", "reddit", "hacker_news", "bing", "youtube", "linkedin", "facebook", "instagram", "direct", "internal", "other", "app", "newsletter", "product_hunt", "discord", "slack", "mastodon", "bluesky", "podcast"]),
device: new Set(["mobile", "tablet", "desktop", "bot", "cli", "unknown"]),
outcome: new Set([...OPERATION_OUTCOMES, "unsupported_os", "unsupported_arch", "download_failed", "checksum_mismatch", "unknown", "matched", "limit", "reset", "revoked", "error", "busy", "too_large", "conflict", "in_flight", "delivered", "delivery_uncertain"]),
Expand Down Expand Up @@ -96,6 +96,10 @@ export function posthogPayload(event: string, id: string, input: Record<string,
if (typeof input.campaign_source === "string" && VALUES.source.has(input.campaign_source) &&
!["direct", "internal", "app", "other"].includes(input.campaign_source)) properties.utm_source = input.campaign_source;
if (properties.medium) properties.utm_medium = properties.medium;
// A /start/ page key the site chose (defined in PostHog, or "default"), never raw campaign text.
if (typeof input.landing_variant === "string" && /^[a-z0-9][a-z0-9_-]{0,31}$/.test(input.landing_variant)) {
properties.landing_variant = input.landing_variant;
}
if (typeof input.referrer_source === "string" && Object.hasOwn(REFERRERS, input.referrer_source)) {
properties.$referring_domain = REFERRERS[input.referrer_source];
properties.$referrer = `https://${REFERRERS[input.referrer_source]}/`;
Expand All @@ -108,7 +112,7 @@ export function posthogPayload(event: string, id: string, input: Record<string,
if (properties.route) {
// Templates only. Never location.href, document.title, referrer or a real session ID.
const host = properties.surface === "app" || properties.surface === "game" ? "app.shell.online" : "shell.online";
const path = properties.route === "landing" ? "/" : properties.route === "terminal" ? "/s/:session" : properties.route === "session" ? "/sessions/:session" :
const path = properties.route === "landing" ? "/" : properties.route === "start" ? "/start/" : properties.route === "terminal" ? "/s/:session" : properties.route === "session" ? "/sessions/:session" :
properties.route === "join" ? "/join/:invite" : properties.route === "cli_authorize" ? "/cli/authorize" :
properties.route === "docs" && properties.guide ? `/${properties.guide}` : `/${properties.route}`;
properties.$current_url = `https://${host}${path}`;
Expand Down
1 change: 1 addition & 0 deletions shared/public-attribution.ts
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,7 @@ export const PUBLIC_CTA_TARGETS = new Set([
"start_nav",
"start_hero",
"start_footer",
"start_share",
"demo",
"github_star",
"signup_nav",
Expand Down
1 change: 1 addition & 0 deletions standalone/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ WORKDIR /src
COPY package.json package-lock.json ./
RUN npm ci
COPY index.html tsconfig.web.json vite.config.ts ./
COPY start ./start
COPY web ./web
COPY shared ./shared
COPY docs ./docs
Expand Down
6 changes: 6 additions & 0 deletions standalone/server.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,11 @@ function sizes(received: Array<string | Buffer>): Array<Record<string, unknown>>
}

const settle = () => new Promise((resolve) => setTimeout(resolve, 40));
/* Wait for what a test expects to arrive, not a fixed time a busy runner can overrun. */
async function until(condition: () => boolean, timeout = 2000): Promise<void> {
const end = Date.now() + timeout;
while (!condition() && Date.now() < end) await new Promise((resolve) => setTimeout(resolve, 10));
}

describe("standalone relay with a host that owns its grid", () => {
test("passes the host's grid on once per change and never resizes for a viewer", async () => {
Expand All @@ -216,6 +221,7 @@ describe("standalone relay with a host that owns its grid", () => {
host.socket.send(JSON.stringify({ type: "terminal_grid", cols: 173, rows: 51 }));
await settle();
phone.socket.close();
await until(() => sizes(desk.received).length > 0);
await settle();

expect(sizes(desk.received)).toEqual([{ type: "terminal_size", cols: 173, rows: 51, dynamic: true }]);
Expand Down
Loading
Loading