Method spawn

packages/cli/src/server/pty/manager.ts:154–244

(opts: SpawnOptions)

	private handles = new Map<string, PtyHandle>();

	spawn(opts: SpawnOptions): {pid: number} {
		const existing = this.handles.get(opts.sessionId);
		if (existing && !existing.exited && existing.pty) {
			throw new Error(
				`Session "${opts.sessionId}" is already running — kill it first or attach to it.`,
			);
		}
		// If there's a stale exited handle, drop it.
		if (existing) this.handles.delete(opts.sessionId);

		const env = {
			...process.env,
			// Override PATH with the login-shell PATH so per-user tool installs
			// (claude, codex, npm global bin) resolve even when the gateway was
			// launched by launchd/systemd with a minimal environment.
			PATH: LOGIN_PATH || process.env.PATH || '',
			...(opts.env ?? {}),
			TERM: 'xterm-256color',
		} as Record<string, string>;

		const resolved = resolveCommand(opts.command);
		if (!resolved) {
			throw new Error(
				`command "${opts.command}" not found on PATH (tried login shell). ` +
					`Install it or set an absolute path in the agent config.`,
			);
		}

		const pty = ptySpawn(resolved, opts.args, {
			name: 'xterm-256color',
			cols: opts.cols ?? 80,
			rows: opts.rows ?? 24,
			cwd: opts.cwd,
			env,
		});

		const handle: PtyHandle = {
			pty,
			outputBuffer: Buffer.alloc(0),
			pendingUtf8: Buffer.alloc(0),
			createdAt: Date.now(),
			cancelled: false,
			exited: false,
			subscribers: new Set(),
			exitSubscribers: new Set(),
			lastActivityAt: Date.now(),
			meta: {
				command: opts.command,
				args: opts.args,
				cwd: opts.cwd,
				agent: opts.agent,
			},
		};

		pty.onData((data) => {
			if (handle.cancelled) return;
			handle.lastActivityAt = Date.now();
			// Append raw bytes to scrollback (for future reconnects)