{"record":{"id":"6634226aed1cc82c","repo":"stablyai/orca","slug":"status-detail-wsl-cli-registration-is-unavai","errorCode":null,"errorMessage":"${status.detail ?? 'WSL CLI registration is unavailable.'}","messagePattern":"\\$\\{status\\.detail \\?\\? 'WSL CLI registration is unavailable\\.'\\}","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/main/cli/wsl-cli-installer.ts","lineNumber":205,"sourceCode":"      status.commandPath &&\n      (await this.isBridgeConflict(this.distro, getBridgePathFromCommandPath(status.commandPath)))\n    ) {\n      // Why: adopting the legacy command would fail install()'s bridge guard\n      // forever; stay registered so reconciliation retries after an update.\n      return { changed: false, managed: true, status }\n    }\n\n    // Why: a legacy-only managed command proves the user opted into WSL CLI\n    // registration; install the current name before removing that owned script.\n    return { changed: true, managed: true, status: await this.install(status) }\n  }\n\n  async install(precomputedStatus?: CliInstallStatus): Promise<CliInstallStatus> {\n    // Why: repair passes its fresh probe; re-probing here would double every\n    // WSL round trip on the startup reconciliation path.\n    const status = precomputedStatus ?? (await this.getStatus())\n    if (!status.supported || !status.commandPath || !status.launcherPath) {\n      throw new Error(status.detail ?? 'WSL CLI registration is unavailable.')\n    }\n    if (status.state === 'conflict') {\n      throw new Error(`Refusing to replace non-Orca command at ${status.commandPath}.`)\n    }\n\n    // Why: the launcher and PowerShell bridge are one registration; the\n    // command replacement stays a single atomic rename (never missing for a\n    // concurrent shell) while a bridge copy enables rollback of the pair.\n    await this.run(\n      this.distro as string,\n      [\n        'set -euo pipefail',\n        `mkdir -p ${quoteShell(status.pathDirectory as string)}`,\n        `mkdir -p ${quoteShell(getPosixDirname(getBridgePathFromCommandPath(status.commandPath)))}`,\n        buildRegistrationLockPrelude(status.commandPath),\n        `command_tmp=${quoteShell(`${status.commandPath}.tmp`)}.$$`,\n        `bridge_path=${quoteShell(getBridgePathFromCommandPath(status.commandPath))}`,\n        `legacy_command_path=${quoteShell(","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/cli/wsl-cli-installer.ts#L187-L223","documentation":"Thrown by WslCliInstaller.install() when getStatus() returns an unsupported status (supported is false, or commandPath/launcherPath are missing). The WSL variant of the host CLI installer's unsupported guard. Uses status.detail if available, otherwise the generic WSL message.","triggerScenarios":"Calling install() on WSL CLI when the distro doesn't support installation, the launcher path can't be resolved, or the status probe failed. Common when WSL is present but the distro doesn't have the required tools (bash, write access to the bin directory).","commonSituations":"WSL distro lacks bash or has a broken PATH. The target bin directory is not writable. WSL version is too old. The PowerShell bridge path can't be resolved. Distro name is stale (uninstalled).","solutions":["Check status.detail for the specific reason.","Verify the WSL distro is functional: 'wsl -d <distro> -- bash -lc echo ok'.","Ensure the user has write access to the target bin directory inside WSL.","Confirm the distro name is correct and still installed: 'wsl -l -v'."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const status = await wslInstaller.getStatus()\nif (!status.supported || !status.commandPath || !status.launcherPath) {\n  showError(status.detail ?? 'WSL CLI registration is unavailable.')\n  return\n}","typeGuard":null,"tryCatchPattern":"try {\n  await wslInstaller.install()\n} catch (error) {\n  if (error instanceof Error && error.message.includes('WSL CLI registration is unavailable')) {\n    // Show status.detail; verify distro functionality\n  } else { throw error }\n}","preventionTips":["Call getStatus() before install() and check supported flag.","Verify WSL distro has bash and writable bin directory.","Keep distro names current after WSL updates."],"tags":["cli-installer","wsl","installation","unsupported"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}