pisper 0.5.43-linux-x64.0 → 0.5.43

package/README.en.md

@@ -0,0 +1,67 @@
+# Pisper TUI Command Reference
+
+[Project home](https://ling-kong-ran.github.io/pisper/) · [GitHub repository](https://github.com/ling-kong-ran/pisper) · [中文](./README.md)
+
+Argument notation: `<argument>` is required; `[argument]` is optional.
+
+## CLI Commands
+
+| Command | Explanation |
+| :--- | :--- |
+| `pisper` | Start the TUI in the current directory with a new empty conversation. History is not resumed automatically. |
+| `pisper --cwd <directory>` | Start the TUI with a new empty conversation in the specified workspace. |
+| `pisper resume` | Open the conversation picker across all workspaces. If no history exists, report it and exit. |
+| `pisper resume --cwd <directory>` | Open the conversation picker from a specified launch directory. A resumed conversation keeps its own saved working directory. |
+| `pisper doctor` | Diagnose the TUI, Runtime connection, and capability catalogs (conversations/tools/skills), then print a summary and exit. |
+| `pisper doctor --cwd <directory>` | Run diagnostics with the specified launch workspace. |
+| `pisper web` | Install (if missing) or use the Web frontend and open its authenticated local settings page in the default browser. The page is served by the Runtime started with this command and stops working once the TUI exits. |
+| `pisper web --cwd <directory>` | Start the Runtime for a specified directory and open the Web settings page. |
+| `pisper help [COMMAND]` | Show global help. `pisper help web` shows help for the Web subcommand. |
+| `pisper -h` / `pisper --help` | Show command help without starting the Runtime. |
+| `pisper -V` / `pisper --version` | Print the installed TUI version. |
+| `pisper update --check` | Check an npm-installed Pisper for updates without installing them. |
+| `pisper update` | Update an npm-installed Pisper through the active npm registry and verify the components again. |
+
+## Environment Variables
+
+| Variable | Description |
+| :--- | :--- |
+| `PISPER_TUI_MOUSE=1` | Enable mouse wheel scrolling in the transcript; mouse capture replaces the terminal's native text selection. |
+| `PISPER_TUI_REDUCED_MOTION=1` | Disable the typewriter reveal and status animations (streaming text appears immediately); useful on low-end terminals and SSH sessions. |
+
+## Slash Commands
+
+| Command | Explanation |
+| :--- | :--- |
+| `/init` | Analyze the current project and create or improve `AGENTS.md` at the project root. Existing useful guidance is preserved, and no other project files are changed. |
+| `/new` | Create an empty conversation in the TUI launch directory. Unavailable during an Agent run. |
+| `/sessions` | Open the conversation picker across all directories. Switching is unavailable during an Agent run. |
+| `/dir <directory>` | Change the active conversation's working directory. Relative paths resolve from its current directory. Unavailable during an Agent run. |
+| `/changes` | Open the Git or SVN changes view. In that view, `R` refreshes, `C` commits, `P` pushes Git, and pressing `V` twice reverts. SVN has no Push operation. |
+| `/changes commit <message>` | Commit the current Git or SVN changes with an explicit message. |
+| `/chat` | Return to the Chat message stream from another view. |
+| `/model` | Open the model picker and switch the active conversation model. Only configured Provider models are listed. Unavailable during an Agent run. |
+| `/thinking` | Refresh and select thinking levels supported by the active model. Unavailable during an Agent run. |
+| `/provider [id]` | Edit a Provider's protocol, effective Base URL, and masked API key. Pass `id` to open a known Provider directly. |
+| `/apikey [id]` | Compatibility alias for `/provider`. |
+| `/web` | Open the authenticated local settings page in the default browser using the installed Web frontend. |
+| `/compact` | Summarize older context immediately. Available only for idle conversations with enough history. |
+| `/attach` | Open the attachment picker rooted at the active conversation directory. |
+| `/mode` | Open the approval mode picker. Unavailable during an Agent run; use `/mode <mode>` directly instead. |
+| `/mode approval-required` | Ask before writes, Shell commands, and high-risk tools. |
+| `/mode workspace-write` | Auto-approve workspace edits and routine commands. |
+| `/mode full-access` | Allow local files, network access, and Shell commands as the current operating-system user. |
+| `/run` | Open the run mode picker (plan / goal / team). Unavailable during an Agent run. |
+| `/run plan` | Plan mode (default): drive the current message by plan, then wait for the next instruction. |
+| `/run goal` | Goal mode: one agent keeps pursuing the objective autonomously until done or paused. |
+| `/run team` | Team mode: a lead agent dynamically coordinates subagents on the objective. |
+| `/run budget <tokens>` | Set the Goal/Team token budget; `off` or an omitted value clears it. Submitted with the message. |
+| `/run pause` | Pause the active goal of the current conversation. |
+| `/quit` | Exit the TUI. |
+
+## Tool and Skill Commands
+
+| Form | Explanation |
+| :--- | :--- |
+| `/<tool> [request]` | Request a Runtime Tool, for example `/read README.md`, `/bash npm test`, or `/web_search Pisper`. The Agent still generates arguments and calls the Tool; the active execution mode and Tool settings remain enforced. |
+| `/skill:<name> [request]` | Request an enabled Skill, for example `/skill:docs-search find signing requirements`. Runtime resources load on demand, and Tools invoked by the Skill follow the same permission chain. |

package/README.md

@@ -1,67 +1,67 @@
-# Pisper TUI Command Reference
+# Pisper TUI 命令参考
 
-[Project home](https://ling-kong-ran.github.io/pisper/) · [GitHub repository](https://github.com/ling-kong-ran/pisper) · [中文](./README.md)
+[项目主页](https://ling-kong-ran.github.io/pisper/) · [GitHub 仓库](https://github.com/ling-kong-ran/pisper) · [English](./README.en.md)
 
-Argument notation: `<argument>` is required; `[argument]` is optional.
+参数约定：`<参数>` 必填，`[参数]` 可选。
 
-## CLI Commands
+## CLI 命令
 
-| Command | Explanation |
+| 命令 | 解释 |
 | :--- | :--- |
-| `pisper` | Start the TUI in the current directory with a new empty conversation. History is not resumed automatically. |
-| `pisper --cwd <directory>` | Start the TUI with a new empty conversation in the specified workspace. |
-| `pisper resume` | Open the conversation picker across all workspaces. If no history exists, report it and exit. |
-| `pisper resume --cwd <directory>` | Open the conversation picker from a specified launch directory. A resumed conversation keeps its own saved working directory. |
-| `pisper doctor` | Diagnose the TUI, Runtime connection, and capability catalogs (conversations/tools/skills), then print a summary and exit. |
-| `pisper doctor --cwd <directory>` | Run diagnostics with the specified launch workspace. |
-| `pisper web` | Install (if missing) or use the Web frontend and open its authenticated local settings page in the default browser. The page is served by the Runtime started with this command and stops working once the TUI exits. |
-| `pisper web --cwd <directory>` | Start the Runtime for a specified directory and open the Web settings page. |
-| `pisper help [COMMAND]` | Show global help. `pisper help web` shows help for the Web subcommand. |
-| `pisper -h` / `pisper --help` | Show command help without starting the Runtime. |
-| `pisper -V` / `pisper --version` | Print the installed TUI version. |
-| `pisper update --check` | Check an npm-installed Pisper for updates without installing them. |
-| `pisper update` | Update an npm-installed Pisper through the active npm registry and verify the components again. |
+| `pisper` | 在当前目录启动 TUI 并创建空会话；不会自动恢复历史会话。 |
+| `pisper --cwd <目录>` | 以指定目录为工作区启动 TUI 并创建空会话。 |
+| `pisper resume` | 打开跨工作目录的历史会话选择器；没有历史会话时提示后退出。 |
+| `pisper resume --cwd <目录>` | 从指定启动目录进入会话选择器；恢复的会话仍使用其自身保存的工作目录。 |
+| `pisper doctor` | 诊断 TUI、Runtime 连接与能力目录（会话/工具/技能），输出摘要后退出。 |
+| `pisper doctor --cwd <目录>` | 以指定目录作为启动工作区执行诊断。 |
+| `pisper web` | 安装（如缺失）或使用 Web 前端，并在默认浏览器打开本机认证配置页；页面由该命令启动的 Runtime 提供，退出 TUI 后不可用。 |
+| `pisper web --cwd <目录>` | 以指定目录启动 Runtime 并打开 Web 配置页。 |
+| `pisper help [COMMAND]` | 显示全局帮助；`pisper help web` 显示 Web 子命令帮助。 |
+| `pisper -h` / `pisper --help` | 显示命令帮助，不启动 Runtime。 |
+| `pisper -V` / `pisper --version` | 显示已安装的 TUI 版本。 |
+| `pisper update --check` | 检查 npm 安装的 Pisper 是否有更新，不执行安装。 |
+| `pisper update` | 通过当前 npm registry 更新 npm 安装的 Pisper，并重新校验组件。 |
 
-## Environment Variables
+## 环境变量
 
-| Variable | Description |
+| 变量 | 解释 |
 | :--- | :--- |
-| `PISPER_TUI_MOUSE=1` | Enable mouse wheel scrolling in the transcript; mouse capture replaces the terminal's native text selection. |
-| `PISPER_TUI_REDUCED_MOTION=1` | Disable the typewriter reveal and status animations (streaming text appears immediately); useful on low-end terminals and SSH sessions. |
+| `PISPER_TUI_MOUSE=1` | 启用鼠标滚轮滚动聊天记录；鼠标捕获会接管终端原生文本选择。 |
+| `PISPER_TUI_REDUCED_MOTION=1` | 关闭打字机逐字显现与状态动画（流式文本立即完整显示），适合低配终端与 SSH 会话。 |
 
-## Slash Commands
+## Slash Command
 
-| Command | Explanation |
+| 命令 | 解释 |
 | :--- | :--- |
-| `/init` | Analyze the current project and create or improve `AGENTS.md` at the project root. Existing useful guidance is preserved, and no other project files are changed. |
-| `/new` | Create an empty conversation in the TUI launch directory. Unavailable during an Agent run. |
-| `/sessions` | Open the conversation picker across all directories. Switching is unavailable during an Agent run. |
-| `/dir <directory>` | Change the active conversation's working directory. Relative paths resolve from its current directory. Unavailable during an Agent run. |
-| `/changes` | Open the Git or SVN changes view. In that view, `R` refreshes, `C` commits, `P` pushes Git, and pressing `V` twice reverts. SVN has no Push operation. |
-| `/changes commit <message>` | Commit the current Git or SVN changes with an explicit message. |
-| `/chat` | Return to the Chat message stream from another view. |
-| `/model` | Open the model picker and switch the active conversation model. Only configured Provider models are listed. Unavailable during an Agent run. |
-| `/thinking` | Refresh and select thinking levels supported by the active model. Unavailable during an Agent run. |
-| `/provider [id]` | Edit a Provider's protocol, effective Base URL, and masked API key. Pass `id` to open a known Provider directly. |
-| `/apikey [id]` | Compatibility alias for `/provider`. |
-| `/web` | Open the authenticated local settings page in the default browser using the installed Web frontend. |
-| `/compact` | Summarize older context immediately. Available only for idle conversations with enough history. |
-| `/attach` | Open the attachment picker rooted at the active conversation directory. |
-| `/mode` | Open the approval mode picker. Unavailable during an Agent run; use `/mode <mode>` directly instead. |
-| `/mode approval-required` | Ask before writes, Shell commands, and high-risk tools. |
-| `/mode workspace-write` | Auto-approve workspace edits and routine commands. |
-| `/mode full-access` | Allow local files, network access, and Shell commands as the current operating-system user. |
-| `/run` | Open the run mode picker (plan / goal / team). Unavailable during an Agent run. |
-| `/run plan` | Plan mode (default): drive the current message by plan, then wait for the next instruction. |
-| `/run goal` | Goal mode: one agent keeps pursuing the objective autonomously until done or paused. |
-| `/run team` | Team mode: a lead agent dynamically coordinates subagents on the objective. |
-| `/run budget <tokens>` | Set the Goal/Team token budget; `off` or an omitted value clears it. Submitted with the message. |
-| `/run pause` | Pause the active goal of the current conversation. |
-| `/quit` | Exit the TUI. |
+| `/init` | 分析当前项目并创建或完善项目根目录的 `AGENTS.md`；保留已有有效说明，不修改其他项目文件。 |
+| `/new` | 在 TUI 启动目录创建空会话；Agent 运行期间不可执行。 |
+| `/sessions` | 打开跨所有目录的历史会话选择器；Agent 运行期间不可切换会话。 |
+| `/dir <目录>` | 修改当前会话的工作目录；相对路径以当前会话目录为基准，Agent 运行期间不可修改。 |
+| `/changes` | 打开 Git 或 SVN 改动视图。视图内 `R` 刷新、`C` 提交、`P` 推送 Git、连续两次 `V` 撤销；SVN 不提供 Push。 |
+| `/changes commit <message>` | 使用指定提交信息提交当前 Git 或 SVN 工作区改动。 |
+| `/chat` | 从其他视图返回 Chat 消息流。 |
+| `/model` | 打开模型选择器并切换当前会话模型；只列出已配置 Provider 的模型，Agent 运行期间不可切换。 |
+| `/thinking` | 刷新并选择当前模型支持的思考等级；Agent 运行期间不可切换。 |
+| `/provider [id]` | 编辑 Provider 协议、当前生效 Base URL 与掩码 API Key；传入 `id` 可直达指定 Provider。 |
+| `/apikey [id]` | `/provider` 的兼容别名。 |
+| `/web` | 使用已安装的 Web 前端，在默认浏览器打开本机认证配置页。 |
+| `/compact` | 立即摘要较早上下文；仅适用于有足够历史且当前空闲的会话。 |
+| `/attach` | 打开当前会话目录的附件选择器。 |
+| `/mode` | 打开审批模式选择器；Agent 运行期间不可打开，此时可改用 `/mode <模式>` 直接切换。 |
+| `/mode approval-required` | 写入、Shell 和高风险工具执行前请求授权。 |
+| `/mode workspace-write` | 自动批准工作区修改和常规命令。 |
+| `/mode full-access` | 允许以当前系统用户权限访问本机文件、网络与 Shell。 |
+| `/run` | 打开运行模式选择器（plan / goal / team）；Agent 运行期间不可打开。 |
+| `/run plan` | 计划模式（默认）：按计划推进当前消息，完成本轮后等待下一条指令。 |
+| `/run goal` | 目标模式：单个 Agent 围绕目标持续自主推进，直到完成或暂停。 |
+| `/run team` | 团队模式：主 Agent 动态组织多个子 Agent 分工协同。 |
+| `/run budget <tokens>` | 设置 Goal/Team 的 Token 预算，`off` 或缺省清除，随消息一起提交。 |
+| `/run pause` | 暂停当前会话的活动目标。 |
+| `/quit` | 退出 TUI。 |
 
-## Tool and Skill Commands
+## Tool 与 Skill 命令
 
-| Form | Explanation |
+| 形式 | 解释 |
 | :--- | :--- |
-| `/<tool> [request]` | Request a Runtime Tool, for example `/read README.md`, `/bash npm test`, or `/web_search Pisper`. The Agent still generates arguments and calls the Tool; the active execution mode and Tool settings remain enforced. |
-| `/skill:<name> [request]` | Request an enabled Skill, for example `/skill:docs-search find signing requirements`. Runtime resources load on demand, and Tools invoked by the Skill follow the same permission chain. |
+| `/<tool> [请求]` | 请求 Runtime Tool，例如 `/read README.md`、`/bash npm test` 或 `/web_search Pisper`。Agent 仍负责生成参数并调用 Tool，当前执行模式与 Tool 开关继续生效。 |
+| `/skill:<name> [请求]` | 请求已启用 Skill，例如 `/skill:docs-search 查找签名要求`。Runtime 按需加载 Skill 资源，其中触发的 Tool 继续经过同一权限链。 |

package/bin/pisper.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { ensurePisperInstallation } from '../lib/install.mjs'
+import { handleNpmHelp, handleNpmUpdate } from '../lib/npm-update.mjs'
+
+const frontendRoot = fileURLToPath(new URL('../web', import.meta.url))
+
+try {
+  const arguments_ = process.argv.slice(2)
+  if (!handleNpmHelp(arguments_) && !(await handleNpmUpdate(arguments_))) {
+    const installation = await ensurePisperInstallation()
+    const child = spawn(installation.executable, arguments_, {
+      env: {
+        ...process.env,
+        PISPER_APP_ROOT: installation.appRoot,
+        PISPER_DISTRIBUTION: 'npm',
+        PISPER_FRONTEND_ROOT: frontendRoot,
+        PISPER_RUNTIME_NODE: process.execPath,
+      },
+      stdio: 'inherit',
+      windowsHide: false,
+    })
+
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+      process.on(signal, () => {
+        if (!child.killed) child.kill(signal)
+      })
+    }
+
+    child.once('error', (error) => {
+      console.error(`pisper: failed to start the terminal client: ${error.message}`)
+      process.exitCode = 1
+    })
+    child.once('exit', (code, signal) => {
+      if (signal) {
+        process.kill(process.pid, signal)
+        return
+      }
+      process.exitCode = code ?? 1
+    })
+  }
+} catch (error) {
+  console.error(`pisper: ${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+}

package/lib/install.mjs

@@ -0,0 +1,392 @@
+import { execFile } from 'node:child_process'
+import { chmod, mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+import { promisify } from 'node:util'
+import { fileURLToPath } from 'node:url'
+import { PublicKey, Signature } from '@threema/wasm-minisign-verify'
+import { x as extractTar } from 'tar'
+import { npmPlatformAlias, npmPlatformTarget, npmPlatformVersion } from './npm-platform.mjs'
+import {
+  componentsRoot,
+  executableName,
+  releaseArchitecture,
+  releasePlatform,
+  supportedTarget,
+} from './platform.mjs'
+
+const execFileAsync = promisify(execFile)
+const require = createRequire(import.meta.url)
+const packageRoot = fileURLToPath(new URL('..', import.meta.url))
+const packageManifest = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'))
+const tuiVersion = packageManifest.pisper?.tuiVersion
+const runtimeVersion = packageManifest.pisper?.runtimeVersion
+const MAX_ARCHIVE_BYTES = 128 * 1024 * 1024
+const INSTALL_WAIT_MS = 600_000
+const LEGACY_LOCK_GRACE_MS = 300_000
+
+for (const [label, value] of [
+  ['TUI', tuiVersion],
+  ['Runtime', runtimeVersion],
+]) {
+  if (!/^\d+\.\d+\.\d+$/.test(value || '')) {
+    throw new Error(`pisper package metadata does not contain a valid ${label} version`)
+  }
+}
+
+function decodeWrapped(value) {
+  const trimmed = String(value).trim()
+  if (trimmed.startsWith('untrusted comment:')) return trimmed
+  if (!/^[A-Za-z0-9+/=\r\n]+$/.test(trimmed)) return trimmed
+  const decoded = Buffer.from(trimmed.replace(/\s/g, ''), 'base64').toString('utf8').trim()
+  return decoded.startsWith('untrusted comment:') ? decoded : trimmed
+}
+
+function componentAsset(component, version, platform = process.platform, arch = process.arch) {
+  const target = supportedTarget(platform, arch)
+  const label = component === 'tui' ? 'TUI_Component' : 'Runtime_Node'
+  return `Pisper_${label}_${version}_${target}.tar.gz`
+}
+
+export function releaseAsset(
+  version = tuiVersion,
+  platform = process.platform,
+  arch = process.arch,
+) {
+  return componentAsset('tui', version, platform, arch)
+}
+
+function compareVersions(left, right) {
+  const a = left.split('.').map(Number)
+  const b = right.split('.').map(Number)
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index]
+  }
+  return 0
+}
+
+async function isFile(path) {
+  try {
+    return (await stat(path)).isFile()
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+function commandName(component) {
+  if (component === 'tui') return executableName()
+  return 'sidecar-runtime/runtime/sidecar.mjs'
+}
+
+async function validateComponent(component, version, destination) {
+  const executable = join(destination, commandName(component))
+  if (!(await isFile(executable))) return ''
+  if (
+    component === 'runtime' &&
+    !(await isFile(join(destination, 'sidecar-runtime', 'package.json')))
+  ) {
+    return ''
+  }
+  try {
+    const manifest = JSON.parse(await readFile(join(destination, 'manifest.json'), 'utf8'))
+    if (
+      manifest.version !== version ||
+      manifest.platform !== releasePlatform() ||
+      manifest.arch !== releaseArchitecture() ||
+      manifest.command !== commandName(component)
+    ) {
+      return ''
+    }
+  } catch {
+    return ''
+  }
+  return executable
+}
+
+async function installedComponent(component, version, destination) {
+  const executable = await validateComponent(component, version, destination)
+  return executable ? { version, destination, executable } : null
+}
+
+async function resolveCurrentComponent(root, component, minimumVersion) {
+  try {
+    const pointer = JSON.parse(await readFile(join(root, component, 'current.json'), 'utf8'))
+    if (!/^\d+\.\d+\.\d+$/.test(pointer.version || '')) return null
+    if (compareVersions(pointer.version, minimumVersion) < 0) return null
+    const destination = join(root, component, 'versions', pointer.version)
+    return installedComponent(component, pointer.version, destination)
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error instanceof SyntaxError) return null
+    throw error
+  }
+}
+
+async function resolvePlatformBundle() {
+  const target = npmPlatformTarget()
+  const alias = npmPlatformAlias()
+  let manifestPath
+  try {
+    manifestPath = require.resolve(`${alias}/package.json`)
+  } catch (error) {
+    throw new Error(
+      `the npm platform package ${alias} is missing; reinstall pisper without --omit=optional`,
+      { cause: error },
+    )
+  }
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+  const metadata = manifest.pisperBundle
+  const expectedVersion = npmPlatformVersion(packageManifest.version)
+  if (
+    manifest.name !== 'pisper' ||
+    manifest.version !== expectedVersion ||
+    metadata?.target !== target.release ||
+    metadata?.tuiVersion !== tuiVersion ||
+    metadata?.runtimeVersion !== runtimeVersion
+  ) {
+    throw new Error(
+      `npm platform package ${alias} does not match pisper@${packageManifest.version}`,
+    )
+  }
+  return dirname(manifestPath)
+}
+
+async function readBundledAsset(bundleRoot, component, version) {
+  const asset = componentAsset(component, version)
+  const archivePath = join(bundleRoot, 'components', component, asset)
+  const signaturePath = `${archivePath}.sig`
+  let size
+  try {
+    size = (await stat(archivePath)).size
+  } catch (error) {
+    throw new Error(`npm platform package is missing ${component} archive ${asset}`, {
+      cause: error,
+    })
+  }
+  if (size <= 0 || size > MAX_ARCHIVE_BYTES) {
+    throw new Error(`npm platform package contains an invalid ${component} archive size: ${size}`)
+  }
+  const [archive, signature] = await Promise.all([readFile(archivePath), readFile(signaturePath)])
+  return { archive, signature }
+}
+
+async function verifyArchive(component, archive, signatureBytes) {
+  const publicKeyText = await readFile(join(packageRoot, 'updater.pubkey'), 'utf8')
+  const publicKey = PublicKey.decode(decodeWrapped(publicKeyText))
+  const signature = Signature.decode(decodeWrapped(signatureBytes.toString('utf8')))
+  try {
+    if (!publicKey.verify(archive, signature)) {
+      throw new Error('signature verification returned false')
+    }
+  } catch (error) {
+    throw new Error(`${component} archive signature verification failed: ${error.message}`, {
+      cause: error,
+    })
+  } finally {
+    signature.free()
+    publicKey.free()
+  }
+}
+
+function nativeTarCommand() {
+  if (process.platform === 'win32') {
+    return join(
+      process.env.SystemRoot || process.env.WINDIR || 'C:\\Windows',
+      'System32',
+      'tar.exe',
+    )
+  }
+  if (process.platform === 'darwin') return '/usr/bin/tar'
+  return 'tar'
+}
+
+async function extractWithNodeTar(archivePath, extractionRoot) {
+  await extractTar({
+    cwd: extractionRoot,
+    file: archivePath,
+    preservePaths: false,
+    strict: true,
+    strip: 1,
+    filter: (_path, entry) => entry.type === 'File' || entry.type === 'Directory',
+  })
+}
+
+export async function extractComponentArchive(
+  archivePath,
+  extractionRoot,
+  tarCommand = nativeTarCommand(),
+) {
+  try {
+    await execFileAsync(
+      tarCommand,
+      ['-xzf', archivePath, '-C', extractionRoot, '--strip-components=1'],
+      { windowsHide: true },
+    )
+  } catch {
+    await rm(extractionRoot, { recursive: true, force: true })
+    await mkdir(extractionRoot, { recursive: true })
+    await extractWithNodeTar(archivePath, extractionRoot)
+  }
+}
+
+async function wait(milliseconds) {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+async function installerLockIsActive(lockPath) {
+  try {
+    const [raw, details] = await Promise.all([readFile(lockPath, 'utf8'), stat(lockPath)])
+    const age = Math.max(0, Date.now() - details.mtimeMs)
+    if (age >= INSTALL_WAIT_MS) return false
+
+    let metadata
+    try {
+      metadata = JSON.parse(raw)
+    } catch {
+      // Older installers created empty locks. Give a live legacy install time to finish.
+      return age < LEGACY_LOCK_GRACE_MS
+    }
+    if (!Number.isSafeInteger(metadata?.pid) || metadata.pid <= 0) {
+      return age < LEGACY_LOCK_GRACE_MS
+    }
+    try {
+      process.kill(metadata.pid, 0)
+      return true
+    } catch (error) {
+      if (error?.code === 'ESRCH') return false
+      if (error?.code === 'EPERM') return true
+      throw error
+    }
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+export async function acquireInstallLock(lockPath, validate) {
+  const deadline = Date.now() + INSTALL_WAIT_MS
+  while (true) {
+    try {
+      const lock = await open(lockPath, 'wx')
+      try {
+        await lock.writeFile(`${JSON.stringify({ pid: process.pid, createdAt: Date.now() })}\n`)
+        return lock
+      } catch (error) {
+        await lock.close()
+        await rm(lockPath, { force: true })
+        throw error
+      }
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      if (await validate()) return null
+      if (!(await installerLockIsActive(lockPath))) {
+        try {
+          await rm(lockPath, { force: true })
+          continue
+        } catch (removeError) {
+          if (!['EACCES', 'EBUSY', 'EPERM'].includes(removeError?.code)) throw removeError
+        }
+      }
+      if (Date.now() >= deadline) {
+        throw new Error('timed out waiting for another Pisper installer')
+      }
+      await wait(250)
+    }
+  }
+}
+
+async function installComponent({ root, bundleRoot, component, version, destination }) {
+  const lockRoot = join(root, 'npm')
+  await mkdir(lockRoot, { recursive: true })
+  const lockPath = join(lockRoot, `${component}-install.lock`)
+  const validate = () => validateComponent(component, version, destination)
+  const lock = await acquireInstallLock(lockPath, validate)
+  if (!lock) return { version, destination, executable: await validate() }
+
+  const staging = `${destination}.tmp-${process.pid}-${Date.now()}`
+  // Renaming a tree with paths over MAX_PATH fails on Windows even though tar can extract it.
+  const extractionRoot = process.platform === 'win32' ? destination : staging
+  const archivePath = `${staging}.tar.gz`
+  try {
+    const existing = await validate()
+    if (existing) return { version, destination, executable: existing }
+
+    console.log(`pisper: installing ${component} ${version} from the npm platform package`)
+    await mkdir(dirname(destination), { recursive: true })
+    await rm(extractionRoot, { recursive: true, force: true })
+    await mkdir(extractionRoot, { recursive: true })
+    const { archive, signature } = await readBundledAsset(bundleRoot, component, version)
+    console.log(`pisper: verifying ${component} ${version} signature`)
+    await verifyArchive(component, archive, signature)
+    console.log(`pisper: extracting ${component} ${version}`)
+    await writeFile(archivePath, archive, { mode: 0o600 })
+    await extractComponentArchive(archivePath, extractionRoot)
+    if (process.platform !== 'win32') {
+      await chmod(join(extractionRoot, commandName(component)), 0o755)
+    }
+    const stagedExecutable = await validateComponent(component, version, extractionRoot)
+    if (!stagedExecutable) {
+      throw new Error(`bundled ${component} archive has an invalid package layout`)
+    }
+    if (extractionRoot !== destination) {
+      await rm(destination, { recursive: true, force: true })
+      await rename(staging, destination)
+    }
+    console.log(`pisper: ${component} ${version} is ready`)
+    return { version, destination, executable: join(destination, commandName(component)) }
+  } finally {
+    await lock.close()
+    await Promise.all([
+      rm(lockPath, { force: true }),
+      rm(staging, { recursive: true, force: true }),
+      rm(archivePath, { force: true }),
+    ])
+  }
+}
+
+export async function ensurePisperInstallation() {
+  const root = componentsRoot()
+  const npmTuiDestination = join(root, 'npm', 'versions', tuiVersion)
+  const runtimeDestination = join(root, 'npm-runtime', 'versions', runtimeVersion)
+  const [tui, runtime] = await Promise.all([
+    resolveCurrentComponent(root, 'tui', tuiVersion).then(
+      (current) => current || installedComponent('tui', tuiVersion, npmTuiDestination),
+    ),
+    installedComponent('runtime', runtimeVersion, runtimeDestination),
+  ])
+  if (tui && runtime) {
+    return {
+      executable: tui.executable,
+      appRoot: join(runtime.destination, 'sidecar-runtime'),
+    }
+  }
+
+  const bundleRoot = await resolvePlatformBundle()
+  const [installedTui, installedRuntime] = await Promise.all([
+    tui ||
+      installComponent({
+        root,
+        bundleRoot,
+        component: 'tui',
+        version: tuiVersion,
+        destination: npmTuiDestination,
+      }),
+    runtime ||
+      installComponent({
+        root,
+        bundleRoot,
+        component: 'runtime',
+        version: runtimeVersion,
+        destination: runtimeDestination,
+      }),
+  ])
+  return {
+    executable: installedTui.executable,
+    appRoot: join(installedRuntime.destination, 'sidecar-runtime'),
+  }
+}
+
+export async function ensurePisperExecutable() {
+  return (await ensurePisperInstallation()).executable
+}