refactor(core): consolidate pty service (#30537)

packages/core/package.json

@@ -8,6 +8,7 @@
   "scripts": {
     "db": "bun drizzle-kit",
     "migration": "bun run script/migration.ts",
+    "fix-node-pty": "bun run script/fix-node-pty.ts",
     "test": "bun test",
     "test:ci": "mkdir -p .artifacts/unit && bun test --timeout 30000 --reporter=junit --reporter-outfile=.artifacts/unit/junit.xml",
     "typecheck": "tsgo --noEmit"
@@ -23,6 +24,11 @@
       "bun": "./src/database/sqlite.bun.ts",
       "node": "./src/database/sqlite.node.ts",
       "default": "./src/database/sqlite.bun.ts"
+    },
+    "#pty": {
+      "bun": "./src/pty/pty.bun.ts",
+      "node": "./src/pty/pty.node.ts",
+      "default": "./src/pty/pty.bun.ts"
     }
   },
   "devDependencies": {
@@ -69,6 +75,7 @@
     "@effect/opentelemetry": "catalog:",
     "@effect/platform-node": "catalog:",
     "@effect/sql-sqlite-bun": "catalog:",
+    "@lydell/node-pty": "catalog:",
     "@npmcli/arborist": "9.4.0",
     "@npmcli/config": "10.8.1",
     "@opencode-ai/effect-drizzle-sqlite": "workspace:*",
@@ -80,6 +87,7 @@
     "@parcel/watcher": "2.5.1",
     "@openrouter/ai-sdk-provider": "2.8.1",
     "ai-gateway-provider": "3.1.2",
+    "bun-pty": "0.4.8",
     "cross-spawn": "catalog:",
     "drizzle-orm": "catalog:",
     "effect": "catalog:",

packages/core/script/fix-node-pty.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+
+import fs from "fs/promises"
+import path from "path"
+import { fileURLToPath } from "url"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const dir = path.resolve(__dirname, "..")
+
+if (process.platform !== "win32") {
+  const root = path.join(dir, "node_modules", "node-pty", "prebuilds")
+  const dirs = await fs.readdir(root, { withFileTypes: true }).catch(() => [])
+  const files = dirs.filter((x) => x.isDirectory()).map((x) => path.join(root, x.name, "spawn-helper"))
+  const result = await Promise.all(
+    files.map(async (file) => {
+      const stat = await fs.stat(file).catch(() => undefined)
+      if (!stat) return
+      if ((stat.mode & 0o111) === 0o111) return
+      await fs.chmod(file, stat.mode | 0o755)
+      return file
+    }),
+  )
+  const fixed = result.filter(Boolean)
+  if (fixed.length) {
+    console.log(`fixed node-pty permissions for ${fixed.length} helper${fixed.length === 1 ? "" : "s"}`)
+  }
+}

packages/core/src/location-layer.ts

@@ -21,6 +21,7 @@ import { FileSystem } from "./filesystem"
 import { Watcher } from "./filesystem/watcher"
 import { ProjectReference } from "./project-reference"
 import { RepositoryCache } from "./repository-cache"
+import { Pty } from "./pty"
 
 export class LocationServiceMap extends LayerMap.Service<LocationServiceMap>()("@opencode/example/LocationServiceMap", {
   lookup: (ref: Location.Ref) => {
@@ -37,6 +38,7 @@ export class LocationServiceMap extends LayerMap.Service<LocationServiceMap>()("
       PermissionV2.locationLayer,
       FileSystem.locationLayer,
       Watcher.locationLayer,
+      Pty.locationLayer,
     ).pipe(Layer.provideMerge(location), Layer.fresh)
   },
   idleTimeToLive: "60 minutes",

packages/core/src/pty.ts

@@ -0,0 +1,312 @@
+export * as Pty from "./pty"
+
+import type { Disp, Proc } from "#pty"
+import { Context, Effect, Layer, Schema, Types } from "effect"
+import { EventV2 } from "./event"
+import { Location } from "./location"
+import { NonNegativeInt, PositiveInt } from "./schema"
+import { PtyID } from "./pty/schema"
+import { lazy } from "./util/lazy"
+import * as Log from "./util/log"
+
+const log = Log.create({ service: "pty" })
+const BUFFER_LIMIT = 1024 * 1024 * 2
+const BUFFER_CHUNK = 64 * 1024
+const encoder = new TextEncoder()
+const pty = lazy(() => import("#pty"))
+
+type Socket = {
+  readyState: number
+  data?: unknown
+  send: (data: string | Uint8Array | ArrayBuffer) => void
+  close: (code?: number, reason?: string) => void
+}
+
+type Active = {
+  info: Info
+  process: Proc
+  buffer: string
+  bufferCursor: number
+  cursor: number
+  subscribers: Map<unknown, Socket>
+  listeners: Disp[]
+}
+
+const sock = (ws: Socket) => (ws.data && typeof ws.data === "object" ? ws.data : ws)
+
+// WebSocket control frame: 0x00 + UTF-8 JSON.
+const meta = (cursor: number) => {
+  const json = JSON.stringify({ cursor })
+  const bytes = encoder.encode(json)
+  const out = new Uint8Array(bytes.length + 1)
+  out[0] = 0
+  out.set(bytes, 1)
+  return out
+}
+
+export const Info = Schema.Struct({
+  id: PtyID,
+  title: Schema.String,
+  command: Schema.String,
+  args: Schema.Array(Schema.String),
+  cwd: Schema.String,
+  status: Schema.Literals(["running", "exited"]),
+  // Windows ConPTY assigns the child pid asynchronously, so 0 is valid at spawn time.
+  pid: NonNegativeInt,
+}).annotate({ identifier: "Pty" })
+
+export type Info = Types.DeepMutable<typeof Info.Type>
+
+export const CreateInput = Schema.Struct({
+  command: Schema.optional(Schema.String),
+  args: Schema.optional(Schema.Array(Schema.String)),
+  cwd: Schema.optional(Schema.String),
+  title: Schema.optional(Schema.String),
+  env: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+})
+
+export type CreateInput = Types.DeepMutable<typeof CreateInput.Type>
+
+export type PreparedCreate = {
+  readonly command: string
+  readonly args: string[]
+  readonly cwd: string
+  readonly title?: string
+  readonly env: Record<string, string>
+}
+
+export const UpdateInput = Schema.Struct({
+  title: Schema.optional(Schema.String),
+  size: Schema.optional(
+    Schema.Struct({
+      rows: PositiveInt,
+      cols: PositiveInt,
+    }),
+  ),
+})
+
+export type UpdateInput = Types.DeepMutable<typeof UpdateInput.Type>
+
+export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()("Pty.NotFoundError", {
+  ptyID: PtyID,
+}) {}
+
+export const Event = {
+  Created: EventV2.define({ type: "pty.created", schema: { info: Info } }),
+  Updated: EventV2.define({ type: "pty.updated", schema: { info: Info } }),
+  Exited: EventV2.define({ type: "pty.exited", schema: { id: PtyID, exitCode: NonNegativeInt } }),
+  Deleted: EventV2.define({ type: "pty.deleted", schema: { id: PtyID } }),
+}
+
+export interface Interface {
+  readonly list: () => Effect.Effect<Info[]>
+  readonly get: (id: PtyID) => Effect.Effect<Info, NotFoundError>
+  readonly create: (input: PreparedCreate) => Effect.Effect<Info>
+  readonly update: (id: PtyID, input: UpdateInput) => Effect.Effect<Info, NotFoundError>
+  readonly remove: (id: PtyID) => Effect.Effect<void, NotFoundError>
+  readonly resize: (id: PtyID, cols: number, rows: number) => Effect.Effect<void, NotFoundError>
+  readonly write: (id: PtyID, data: string) => Effect.Effect<void, NotFoundError>
+  readonly connect: (
+    id: PtyID,
+    ws: Socket,
+    cursor?: number,
+  ) => Effect.Effect<
+    { onMessage: (message: string | ArrayBuffer) => void; onClose: () => void } | undefined,
+    NotFoundError
+  >
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/v2/Pty") {}
+
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const events = yield* EventV2.Service
+    const location = yield* Location.Service
+    const context = yield* Effect.context()
+    const runFork = Effect.runForkWith(context)
+    const sessions = new Map<PtyID, Active>()
+
+    function teardown(session: Active) {
+      for (const listener of session.listeners) listener.dispose()
+      session.listeners.length = 0
+      try {
+        session.process.kill()
+      } catch {}
+      for (const [sub, ws] of session.subscribers.entries()) {
+        try {
+          if (sock(ws) === sub) ws.close()
+        } catch {}
+      }
+      session.subscribers.clear()
+    }
+
+    yield* Effect.addFinalizer(() =>
+      Effect.sync(() => {
+        for (const session of sessions.values()) teardown(session)
+        sessions.clear()
+      }),
+    )
+
+    const requireSession = Effect.fn("Pty.requireSession")(function* (id: PtyID) {
+      const session = sessions.get(id)
+      if (!session) return yield* new NotFoundError({ ptyID: id })
+      return session
+    })
+
+    const removeSession = Effect.fnUntraced(function* (id: PtyID) {
+      const session = sessions.get(id)
+      if (!session) return false
+      sessions.delete(id)
+      log.info("removing session", { id })
+      teardown(session)
+      yield* events.publish(Event.Deleted, { id: session.info.id })
+      return true
+    })
+
+    const remove = Effect.fn("Pty.remove")(function* (id: PtyID) {
+      yield* requireSession(id)
+      yield* removeSession(id)
+    })
+
+    const list = Effect.fn("Pty.list")(function* () {
+      return Array.from(sessions.values()).map((session) => session.info)
+    })
+
+    const get = Effect.fn("Pty.get")(function* (id: PtyID) {
+      return (yield* requireSession(id)).info
+    })
+
+    const create = Effect.fn("Pty.create")(function* (input: PreparedCreate) {
+      const id = PtyID.ascending()
+      log.info("creating session", { id, cmd: input.command, args: input.args, cwd: input.cwd })
+      const { spawn } = yield* Effect.promise(() => pty())
+      const proc = yield* Effect.sync(() =>
+        spawn(input.command, input.args, {
+          name: "xterm-256color",
+          cwd: input.cwd,
+          env: input.env,
+        }),
+      )
+      const info = {
+        id,
+        title: input.title || `Terminal ${id.slice(-4)}`,
+        command: input.command,
+        args: input.args,
+        cwd: input.cwd,
+        status: "running",
+        pid: proc.pid,
+      } as const
+      const session: Active = {
+        info,
+        process: proc,
+        buffer: "",
+        bufferCursor: 0,
+        cursor: 0,
+        subscribers: new Map(),
+        listeners: [],
+      }
+      sessions.set(id, session)
+      session.listeners.push(
+        proc.onData((chunk) => {
+          session.cursor += chunk.length
+          for (const [key, ws] of session.subscribers.entries()) {
+            if (ws.readyState !== 1 || sock(ws) !== key) {
+              session.subscribers.delete(key)
+              continue
+            }
+            try {
+              ws.send(chunk)
+            } catch {
+              session.subscribers.delete(key)
+            }
+          }
+          session.buffer += chunk
+          if (session.buffer.length <= BUFFER_LIMIT) return
+          const excess = session.buffer.length - BUFFER_LIMIT
+          session.buffer = session.buffer.slice(excess)
+          session.bufferCursor += excess
+        }),
+        proc.onExit(({ exitCode }) => {
+          if (session.info.status === "exited") return
+          runFork(
+            Effect.gen(function* () {
+              log.info("session exited", { id, exitCode })
+              session.info.status = "exited"
+              yield* events.publish(Event.Exited, { id, exitCode })
+              yield* removeSession(id)
+            }),
+          )
+        }),
+      )
+      yield* events.publish(Event.Created, { info })
+      return info
+    })
+
+    const update = Effect.fn("Pty.update")(function* (id: PtyID, input: UpdateInput) {
+      const session = yield* requireSession(id)
+      if (input.title) session.info.title = input.title
+      if (input.size) session.process.resize(input.size.cols, input.size.rows)
+      yield* events.publish(Event.Updated, { info: session.info })
+      return session.info
+    })
+
+    const resize = Effect.fn("Pty.resize")(function* (id: PtyID, cols: number, rows: number) {
+      const session = yield* requireSession(id)
+      if (session.info.status === "running") session.process.resize(cols, rows)
+    })
+
+    const write = Effect.fn("Pty.write")(function* (id: PtyID, data: string) {
+      const session = yield* requireSession(id)
+      if (session.info.status === "running") session.process.write(data)
+    })
+
+    const connect = Effect.fn("Pty.connect")(function* (id: PtyID, ws: Socket, cursor?: number) {
+      const session = yield* requireSession(id).pipe(Effect.tapError(() => Effect.sync(() => ws.close())))
+      log.info("client connected to session", { id, directory: location.directory })
+      const sub = sock(ws)
+      session.subscribers.delete(sub)
+      session.subscribers.set(sub, ws)
+      const cleanup = () => session.subscribers.delete(sub)
+      const start = session.bufferCursor
+      const end = session.cursor
+      const from =
+        cursor === -1 ? end : typeof cursor === "number" && Number.isSafeInteger(cursor) ? Math.max(0, cursor) : 0
+      const data = (() => {
+        if (!session.buffer || from >= end) return ""
+        const offset = Math.max(0, from - start)
+        if (offset >= session.buffer.length) return ""
+        return session.buffer.slice(offset)
+      })()
+      if (data) {
+        try {
+          for (let i = 0; i < data.length; i += BUFFER_CHUNK) ws.send(data.slice(i, i + BUFFER_CHUNK))
+        } catch {
+          cleanup()
+          ws.close()
+          return
+        }
+      }
+      try {
+        ws.send(meta(end))
+      } catch {
+        cleanup()
+        ws.close()
+        return
+      }
+      return {
+        onMessage: (message: string | ArrayBuffer) => {
+          session.process.write(typeof message === "string" ? message : new TextDecoder().decode(message))
+        },
+        onClose: () => {
+          log.info("client disconnected from session", { id })
+          cleanup()
+        },
+      }
+    })
+
+    return Service.of({ list, get, create, update, remove, resize, write, connect })
+  }),
+)
+
+export const locationLayer = layer

packages/core/src/pty/input.ts

@@ -0,0 +1,24 @@
+import { Effect } from "effect"
+
+const inputDecoder = new TextDecoder("utf-8", { fatal: true })
+
+export function handlePtyInput(
+  handler: { onMessage: (message: string | ArrayBuffer) => void },
+  message: string | Uint8Array,
+) {
+  if (typeof message === "string") {
+    handler.onMessage(message)
+    return Effect.void
+  }
+  return Effect.try({
+    try: () => inputDecoder.decode(message),
+    catch: () => new Error("invalid PTY websocket input"),
+  }).pipe(
+    Effect.catch(() => Effect.succeed(undefined)),
+    Effect.flatMap((decoded) => {
+      if (decoded === undefined) return Effect.void
+      handler.onMessage(decoded)
+      return Effect.void
+    }),
+  )
+}

packages/core/src/pty/pty.bun.ts

@@ -0,0 +1,26 @@
+import { spawn as create } from "bun-pty"
+import type { Opts, Proc } from "./pty"
+
+export type { Disp, Exit, Opts, Proc } from "./pty"
+
+export function spawn(file: string, args: string[], opts: Opts): Proc {
+  const pty = create(file, args, opts)
+  return {
+    pid: pty.pid,
+    onData(listener) {
+      return pty.onData(listener)
+    },
+    onExit(listener) {
+      return pty.onExit(listener)
+    },
+    write(data) {
+      pty.write(data)
+    },
+    resize(cols, rows) {
+      pty.resize(cols, rows)
+    },
+    kill(signal) {
+      pty.kill(signal)
+    },
+  }
+}

packages/core/src/pty/pty.node.ts

@@ -0,0 +1,26 @@
+import * as pty from "@lydell/node-pty"
+import type { Opts, Proc } from "./pty"
+
+export type { Disp, Exit, Opts, Proc } from "./pty"
+
+export function spawn(file: string, args: string[], opts: Opts): Proc {
+  const proc = pty.spawn(file, args, opts)
+  return {
+    pid: proc.pid,
+    onData(listener) {
+      return proc.onData(listener)
+    },
+    onExit(listener) {
+      return proc.onExit(listener)
+    },
+    write(data) {
+      proc.write(data)
+    },
+    resize(cols, rows) {
+      proc.resize(cols, rows)
+    },
+    kill(signal) {
+      proc.kill(signal)
+    },
+  }
+}

packages/core/src/pty/pty.ts

@@ -0,0 +1,25 @@
+export type Disp = {
+  dispose(): void
+}
+
+export type Exit = {
+  exitCode: number
+  signal?: number | string
+}
+
+export type Opts = {
+  name: string
+  cols?: number
+  rows?: number
+  cwd?: string
+  env?: Record<string, string>
+}
+
+export type Proc = {
+  pid: number
+  onData(listener: (data: string) => void): Disp
+  onExit(listener: (event: Exit) => void): Disp
+  write(data: string): void
+  resize(cols: number, rows: number): void
+  kill(signal?: string): void
+}

packages/core/src/pty/schema.ts

@@ -0,0 +1,13 @@
+import { Schema } from "effect"
+import { Identifier } from "../id/id"
+import { withStatics } from "../schema"
+
+const ptyIdSchema = Schema.String.check(Schema.isStartsWith("pty")).pipe(Schema.brand("PtyID"))
+
+export type PtyID = typeof ptyIdSchema.Type
+
+export const PtyID = ptyIdSchema.pipe(
+  withStatics((schema: typeof ptyIdSchema) => ({
+    ascending: (id?: string) => schema.make(Identifier.ascending("pty", id)),
+  })),
+)

packages/core/src/pty/ticket.ts

@@ -0,0 +1,58 @@
+export * as PtyTicket from "./ticket"
+
+import { WorkspaceV2 } from "../workspace"
+import { PositiveInt } from "../schema"
+import { PtyID } from "./schema"
+import { Cache, Context, Duration, Effect, Layer, Schema } from "effect"
+
+const DEFAULT_TTL = Duration.seconds(60)
+const CAPACITY = 10_000
+
+export const ConnectToken = Schema.Struct({
+  ticket: Schema.String,
+  expires_in: PositiveInt,
+})
+
+export type Scope = {
+  readonly ptyID: PtyID
+  readonly directory?: string
+  readonly workspaceID?: WorkspaceV2.ID
+}
+
+export interface Interface {
+  issue(input: Scope): Effect.Effect<typeof ConnectToken.Type>
+  consume(input: Scope & { readonly ticket: string }): Effect.Effect<boolean>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/PtyTicket") {}
+
+function matches(record: Scope, input: Scope) {
+  return (
+    record.ptyID === input.ptyID && record.directory === input.directory && record.workspaceID === input.workspaceID
+  )
+}
+
+// Tickets are inserted via Cache.set and removed atomically via invalidateWhen. The lookup is
+// never invoked; it dies if it ever is, which would signal a misuse of the Service interface.
+const noLookup = () => Effect.die("PtyTicket cache must be used via set/invalidateWhen, never get")
+
+// Visible for tests so the TTL can be shortened. Production uses `layer` with the default TTL.
+export const make = (ttl: Duration.Input = DEFAULT_TTL) =>
+  Effect.gen(function* () {
+    const cache = yield* Cache.make<string, Scope>({ capacity: CAPACITY, lookup: noLookup, timeToLive: ttl })
+    const expiresIn = Math.max(1, Math.round(Duration.toSeconds(Duration.fromInputUnsafe(ttl))))
+    return Service.of({
+      issue: Effect.fn("PtyTicket.issue")(function* (input) {
+        const ticket = crypto.randomUUID()
+        yield* Cache.set(cache, ticket, input)
+        return { ticket, expires_in: expiresIn }
+      }),
+      consume: Effect.fn("PtyTicket.consume")(function* (input) {
+        return yield* Cache.invalidateWhen(cache, input.ticket, (stored) => matches(stored, input))
+      }),
+    })
+  })
+
+export const layer = Layer.effect(Service, make())
+
+export const defaultLayer = layer

packages/core/test/pty/info-schema.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test"
+import { Schema } from "effect"
+import { Pty } from "@opencode-ai/core/pty"
+
+const sample = (pid: number) => ({
+  id: "pty_01J5Y5H0AH4Q4NXJ6P4C3P5V2K",
+  title: "demo",
+  command: "cmd.exe",
+  args: [],
+  cwd: "C:\\",
+  status: "running",
+  pid,
+})
+
+describe("Pty.Info", () => {
+  test("accepts pid 0 (Windows ConPTY assigns the pid asynchronously)", () => {
+    expect(Schema.decodeUnknownSync(Pty.Info)(sample(0)).pid).toBe(0)
+  })
+
+  test("accepts a positive pid", () => {
+    expect(Schema.decodeUnknownSync(Pty.Info)(sample(48012)).pid).toBe(48012)
+  })
+
+  test("rejects a negative pid", () => {
+    expect(() => Schema.decodeUnknownSync(Pty.Info)(sample(-1))).toThrow()
+  })
+})

packages/core/test/pty/input.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { handlePtyInput } from "@opencode-ai/core/pty/input"
+import { it } from "../lib/effect"
+
+describe("pty websocket input", () => {
+  it.effect("does not forward invalid binary frames to the PTY handler", () =>
+    Effect.gen(function* () {
+      const messages: Array<string | ArrayBuffer> = []
+      const handler = { onMessage: (message: string | ArrayBuffer) => messages.push(message) }
+
+      yield* handlePtyInput(handler, "ready")
+      yield* handlePtyInput(handler, new Uint8Array([0xff, 0xfe, 0xfd]))
+      yield* handlePtyInput(handler, new TextEncoder().encode("hello"))
+
+      expect(messages).toEqual(["ready", "hello"])
+    }),
+  )
+})

packages/core/test/pty/pty-output-isolation.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect } from "bun:test"
+import { Duration, Effect, Layer, Queue } from "effect"
+import { EventV2 } from "@opencode-ai/core/event"
+import { Location } from "@opencode-ai/core/location"
+import { Pty } from "@opencode-ai/core/pty"
+import { AbsolutePath } from "@opencode-ai/core/schema"
+import { location } from "../fixture/location"
+import { testEffect } from "../lib/effect"
+
+type Socket = Parameters<Pty.Interface["connect"]>[1]
+
+const locationLayer = Layer.succeed(
+  Location.Service,
+  Location.Service.of(location({ directory: AbsolutePath.make("/tmp") })),
+)
+const it = testEffect(Pty.layer.pipe(Layer.provideMerge(EventV2.defaultLayer), Layer.provideMerge(locationLayer)))
+const ptyTest = process.platform === "win32" ? it.live.skip : it.live
+
+const createPty = Effect.fn("PtyOutputIsolationTest.createPty")(function* (command: string) {
+  const pty = yield* Pty.Service
+  return yield* Effect.acquireRelease(
+    pty.create({ command, args: [], cwd: "/tmp", env: { TERM: "xterm-256color", OPENCODE_TERMINAL: "1" } }),
+    (info) => pty.remove(info.id).pipe(Effect.ignore),
+  )
+})
+
+const decodeOutput = (data: string | Uint8Array | ArrayBuffer) =>
+  typeof data === "string"
+    ? data
+    : Buffer.from(data instanceof Uint8Array ? data : new Uint8Array(data)).toString("utf8")
+
+const makeSocket = Effect.fn("PtyOutputIsolationTest.makeSocket")(function* (data: unknown) {
+  const output = yield* Queue.unbounded<string>()
+  const socket: Socket = {
+    readyState: 1,
+    data,
+    send: (data) => Queue.offerUnsafe(output, decodeOutput(data)),
+    close: () => {},
+  }
+  return { socket, output }
+})
+
+const waitForOutput = (output: Queue.Queue<string>, text: string, duration: Duration.Input = "5 seconds") =>
+  Effect.gen(function* () {
+    let received = ""
+    while (!received.includes(text)) received += yield* Queue.take(output)
+    return received
+  }).pipe(
+    Effect.timeoutOrElse({
+      duration,
+      orElse: () => Effect.fail(new Error(`timeout waiting for output containing ${JSON.stringify(text)}`)),
+    }),
+  )
+
+describe("pty output isolation", () => {
+  ptyTest("does not leak output when websocket objects are reused", () =>
+    Effect.gen(function* () {
+      const pty = yield* Pty.Service
+      const a = yield* createPty("cat")
+      const b = yield* createPty("cat")
+      const shared = yield* makeSocket({ events: { connection: "a" } })
+      const outB = yield* Queue.unbounded<string>()
+
+      yield* pty.connect(a.id, shared.socket)
+      shared.socket.data = { events: { connection: "b" } }
+      shared.socket.send = (data) => Queue.offerUnsafe(outB, decodeOutput(data))
+      yield* pty.connect(b.id, shared.socket)
+      yield* pty.write(a.id, "AAA\n")
+
+      const verify = yield* makeSocket({ events: { connection: "verify-a" } })
+      yield* pty.connect(a.id, verify.socket)
+      expect(yield* waitForOutput(verify.output, "AAA")).toContain("AAA")
+      expect(yield* waitForOutput(outB, "AAA", "100 millis").pipe(Effect.option)).toMatchObject({ _tag: "None" })
+    }),
+  )
+
+  ptyTest("does not leak output when Bun recycles websocket objects before re-connect", () =>
+    Effect.gen(function* () {
+      const pty = yield* Pty.Service
+      const info = yield* createPty("cat")
+      const first = yield* makeSocket({ events: { connection: "a" } })
+      const recycled = yield* Queue.unbounded<string>()
+
+      yield* pty.connect(info.id, first.socket)
+      first.socket.data = { events: { connection: "b" } }
+      first.socket.send = (data) => Queue.offerUnsafe(recycled, decodeOutput(data))
+      yield* pty.write(info.id, "AAA\n")
+
+      const verify = yield* makeSocket({ events: { connection: "verify" } })
+      yield* pty.connect(info.id, verify.socket)
+      expect(yield* waitForOutput(verify.output, "AAA")).toContain("AAA")
+      expect(yield* waitForOutput(recycled, "AAA", "100 millis").pipe(Effect.option)).toMatchObject({ _tag: "None" })
+    }),
+  )
+
+  ptyTest("treats in-place socket data mutation as the same connection", () =>
+    Effect.gen(function* () {
+      const pty = yield* Pty.Service
+      const info = yield* createPty("cat")
+      const data = { connId: 1 }
+      const socket = yield* makeSocket(data)
+
+      yield* pty.connect(info.id, socket.socket)
+      data.connId = 2
+      yield* pty.write(info.id, "AAA\n")
+
+      expect(yield* waitForOutput(socket.output, "AAA")).toContain("AAA")
+    }),
+  )
+})

packages/core/test/pty/pty-session.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect } from "bun:test"
+import { Cause, Effect, Exit, Layer, Queue } from "effect"
+import { EventV2 } from "@opencode-ai/core/event"
+import { Location } from "@opencode-ai/core/location"
+import { Pty } from "@opencode-ai/core/pty"
+import type { PtyID } from "@opencode-ai/core/pty/schema"
+import { AbsolutePath } from "@opencode-ai/core/schema"
+import { location } from "../fixture/location"
+import { testEffect } from "../lib/effect"
+
+type PtyEvent = { type: "created" | "exited" | "deleted"; id: PtyID }
+
+const locationLayer = Layer.succeed(
+  Location.Service,
+  Location.Service.of(location({ directory: AbsolutePath.make("/tmp") })),
+)
+const it = testEffect(Pty.layer.pipe(Layer.provideMerge(EventV2.defaultLayer), Layer.provideMerge(locationLayer)))
+const ptyTest = process.platform === "win32" ? it.live.skip : it.live
+
+const subscribePtyEvents = Effect.fn("PtySessionTest.subscribePtyEvents")(function* () {
+  const source = yield* EventV2.Service
+  const events = yield* Queue.unbounded<PtyEvent>()
+  const unsubscribe = yield* source.listen((event) => {
+    if (event.type === Pty.Event.Created.type)
+      Queue.offerUnsafe(events, { type: "created", id: (event.data as typeof Pty.Event.Created.data.Type).info.id })
+    if (event.type === Pty.Event.Exited.type)
+      Queue.offerUnsafe(events, { type: "exited", id: (event.data as typeof Pty.Event.Exited.data.Type).id })
+    if (event.type === Pty.Event.Deleted.type)
+      Queue.offerUnsafe(events, { type: "deleted", id: (event.data as typeof Pty.Event.Deleted.data.Type).id })
+    return Effect.void
+  })
+  yield* Effect.addFinalizer(() => unsubscribe)
+  return events
+})
+
+const createPty = Effect.fn("PtySessionTest.createPty")(function* (command: string, args: string[] = []) {
+  const pty = yield* Pty.Service
+  return yield* Effect.acquireRelease(
+    pty.create({ command, args, cwd: "/tmp", env: { TERM: "xterm-256color", OPENCODE_TERMINAL: "1" } }),
+    (info) => pty.remove(info.id).pipe(Effect.ignore),
+  )
+})
+
+const waitForEvents = (events: Queue.Queue<PtyEvent>, id: PtyID, count: number) =>
+  Effect.gen(function* () {
+    const picked: Array<PtyEvent["type"]> = []
+    while (picked.length < count) {
+      const evt = yield* Queue.take(events)
+      if (evt.id === id) picked.push(evt.type)
+    }
+    return picked
+  }).pipe(
+    Effect.timeoutOrElse({
+      duration: "5 seconds",
+      orElse: () => Effect.fail(new Error("timeout waiting for pty events")),
+    }),
+  )
+
+describe("pty", () => {
+  it.live("returns typed not found errors for missing sessions", () =>
+    Effect.gen(function* () {
+      const pty = yield* Pty.Service
+      const id = "pty_missing" as PtyID
+      let closed = false
+      const socket = { readyState: 1, send: () => {}, close: () => void (closed = true) }
+
+      for (const result of [
+        yield* pty.get(id).pipe(Effect.asVoid, Effect.exit),
+        yield* pty.update(id, { title: "missing" }).pipe(Effect.asVoid, Effect.exit),
+        yield* pty.remove(id).pipe(Effect.exit),
+        yield* pty.resize(id, 80, 24).pipe(Effect.exit),
+        yield* pty.write(id, "input").pipe(Effect.exit),
+        yield* pty.connect(id, socket).pipe(Effect.asVoid, Effect.exit),
+      ]) {
+        expect(Exit.isFailure(result)).toBe(true)
+        if (Exit.isFailure(result))
+          expect(Cause.squash(result.cause)).toMatchObject({ _tag: "Pty.NotFoundError", ptyID: id })
+      }
+      expect(closed).toBe(true)
+    }),
+  )
+
+  ptyTest("publishes created, exited, deleted in order for a short-lived process", () =>
+    Effect.gen(function* () {
+      const events = yield* subscribePtyEvents()
+      const info = yield* createPty("/usr/bin/env", ["sh", "-c", "sleep 0.1"])
+
+      expect(yield* waitForEvents(events, info.id, 3)).toEqual(["created", "exited", "deleted"])
+    }),
+  )
+})

packages/core/test/pty/ticket.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect } from "bun:test"
+import { Effect, Layer } from "effect"
+import { PtyID } from "@opencode-ai/core/pty/schema"
+import { PtyTicket } from "@opencode-ai/core/pty/ticket"
+import { WorkspaceV2 } from "@opencode-ai/core/workspace"
+import { testEffect } from "../lib/effect"
+
+const it = testEffect(PtyTicket.layer)
+const itExpiring = testEffect(Layer.effect(PtyTicket.Service, PtyTicket.make(5)))
+
+describe("PTY websocket tickets", () => {
+  it.live("consumes tickets once", () =>
+    Effect.gen(function* () {
+      const tickets = yield* PtyTicket.Service
+      const scope = { ptyID: PtyID.ascending(), directory: "/tmp/a" }
+      const issued = yield* tickets.issue(scope)
+
+      expect(yield* tickets.consume({ ...scope, ticket: issued.ticket })).toBe(true)
+      expect(yield* tickets.consume({ ...scope, ticket: issued.ticket })).toBe(false)
+    }),
+  )
+
+  it.live("rejects tickets scoped to a different request", () =>
+    Effect.gen(function* () {
+      const tickets = yield* PtyTicket.Service
+      const ptyID = PtyID.ascending()
+      const issued = yield* tickets.issue({ ptyID, directory: "/tmp/a" })
+
+      expect(yield* tickets.consume({ ptyID, directory: "/tmp/b", ticket: issued.ticket })).toBe(false)
+      expect(yield* tickets.consume({ ptyID, directory: "/tmp/a", ticket: issued.ticket })).toBe(true)
+    }),
+  )
+
+  itExpiring.live("rejects tickets after the TTL elapses", () =>
+    Effect.gen(function* () {
+      const tickets = yield* PtyTicket.Service
+      const ptyID = PtyID.ascending()
+      const issued = yield* tickets.issue({ ptyID })
+
+      yield* Effect.promise(() => new Promise((resolve) => setTimeout(resolve, 25)))
+
+      expect(yield* tickets.consume({ ptyID, ticket: issued.ticket })).toBe(false)
+    }),
+  )
+
+  it.live("rejects tickets scoped to a different workspace", () =>
+    Effect.gen(function* () {
+      const tickets = yield* PtyTicket.Service
+      const ptyID = PtyID.ascending()
+      const workspaceID = WorkspaceV2.ID.ascending()
+      const issued = yield* tickets.issue({ ptyID, workspaceID })
+
+      expect(yield* tickets.consume({ ptyID, workspaceID: WorkspaceV2.ID.ascending(), ticket: issued.ticket })).toBe(
+        false,
+      )
+      expect(yield* tickets.consume({ ptyID, workspaceID, ticket: issued.ticket })).toBe(true)
+    }),
+  )
+})