@rover-studio/answer-me 0.1.0-rc.1

package/distribution/npm/skills/answerme/scripts/windows-crypto.ps1

@@ -0,0 +1,57 @@
+$ErrorActionPreference = 'Stop'
+
+function Clear-AnswerMeSensitiveByteArray {
+    param([AllowNull()][byte[]]$Bytes)
+
+    if ($null -ne $Bytes -and $Bytes.Length -gt 0) {
+        [Array]::Clear($Bytes, 0, $Bytes.Length)
+    }
+}
+
+function Get-AnswerMeSha256Bytes {
+    param([Parameter(Mandatory = $true)][byte[]]$Bytes)
+
+    $algorithm = [Security.Cryptography.SHA256]::Create()
+    try {
+        return ,$algorithm.ComputeHash($Bytes)
+    }
+    finally {
+        $algorithm.Dispose()
+    }
+}
+
+function ConvertTo-AnswerMeLowerHex {
+    param([Parameter(Mandatory = $true)][byte[]]$Bytes)
+
+    return [BitConverter]::ToString($Bytes).Replace('-', '').ToLowerInvariant()
+}
+
+function New-AnswerMeCryptographicRandomBytes {
+    param([Parameter(Mandatory = $true)][ValidateRange(1, 4096)][int]$Length)
+
+    $bytes = New-Object byte[] $Length
+    $generator = [Security.Cryptography.RandomNumberGenerator]::Create()
+    try {
+        $generator.GetBytes($bytes)
+        return ,$bytes
+    }
+    finally {
+        $generator.Dispose()
+    }
+}
+
+function Test-AnswerMeFixedTimeBytesEqual {
+    param(
+        [Parameter(Mandatory = $true)][byte[]]$Left,
+        [Parameter(Mandatory = $true)][byte[]]$Right
+    )
+
+    [int]$difference = $Left.Length -bxor $Right.Length
+    [int]$comparisonLength = [Math]::Max($Left.Length, $Right.Length)
+    for ($index = 0; $index -lt $comparisonLength; $index += 1) {
+        [int]$leftByte = if ($index -lt $Left.Length) { $Left[$index] } else { 0 }
+        [int]$rightByte = if ($index -lt $Right.Length) { $Right[$index] } else { 0 }
+        $difference = $difference -bor ($leftByte -bxor $rightByte)
+    }
+    return $difference -eq 0
+}

package/distribution/npm/skills/answerme/scripts/windows-http.ps1

@@ -0,0 +1,45 @@
+$ErrorActionPreference = 'Stop'
+
+function Invoke-AnswerMeWebRequest {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)][Uri]$Uri,
+        [ValidateSet('Get', 'Post')][string]$Method = 'Get',
+        [AllowNull()][System.Collections.IDictionary]$Headers,
+        [AllowNull()][string]$ContentType,
+        [AllowNull()][object]$Body,
+        [int]$TimeoutSec = 0
+    )
+
+    $parameters = @{ Uri = $Uri; Method = $Method; ErrorAction = 'Stop' }
+    $command = Get-Command -Name 'Invoke-WebRequest' -CommandType Cmdlet -ErrorAction Stop
+    if ($command.Parameters.ContainsKey('UseBasicParsing')) { $parameters.UseBasicParsing = $true }
+    if ($command.Parameters.ContainsKey('SkipHttpErrorCheck')) { $parameters.SkipHttpErrorCheck = $true }
+    if ($null -ne $Headers) { $parameters.Headers = $Headers }
+    if (-not [string]::IsNullOrWhiteSpace($ContentType)) { $parameters.ContentType = $ContentType }
+    if ($null -ne $Body) { $parameters.Body = $Body }
+    if ($TimeoutSec -gt 0) { $parameters.TimeoutSec = $TimeoutSec }
+
+    try {
+        return Invoke-WebRequest @parameters
+    }
+    catch {
+        $response = $_.Exception.Response
+        if ($null -eq $response -or $response -isnot [Net.HttpWebResponse]) { throw }
+        $stream = $response.GetResponseStream()
+        $reader = $null
+        try {
+            $reader = New-Object IO.StreamReader($stream, [Text.Encoding]::UTF8, $true)
+            $content = $reader.ReadToEnd()
+        }
+        finally {
+            if ($null -ne $reader) { $reader.Dispose() }
+            elseif ($null -ne $stream) { $stream.Dispose() }
+        }
+        return [PSCustomObject]@{
+            StatusCode = [int]$response.StatusCode
+            Headers = $response.Headers
+            Content = $content
+        }
+    }
+}

package/distribution/npm/skills/answerme/scripts/windows-process-start-info.ps1

@@ -0,0 +1,76 @@
+$ErrorActionPreference = 'Stop'
+
+function ConvertTo-AnswerMeWindowsProcessArgument {
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string]$Value
+    )
+
+    if ($Value.IndexOf([char]0) -ge 0) {
+        throw 'Process arguments cannot contain a null character.'
+    }
+
+    $builder = New-Object System.Text.StringBuilder
+    [void]$builder.Append('"')
+    $backslashCount = 0
+    foreach ($character in $Value.ToCharArray()) {
+        if ($character -ceq [char]'\') {
+            $backslashCount += 1
+            continue
+        }
+        if ($character -ceq [char]'"') {
+            if ($backslashCount -gt 0) {
+                [void]$builder.Append((('\' * ($backslashCount * 2)) -join ''))
+            }
+            [void]$builder.Append('\"')
+            $backslashCount = 0
+            continue
+        }
+        if ($backslashCount -gt 0) {
+            [void]$builder.Append((('\' * $backslashCount) -join ''))
+            $backslashCount = 0
+        }
+        [void]$builder.Append($character)
+    }
+    if ($backslashCount -gt 0) {
+        [void]$builder.Append((('\' * ($backslashCount * 2)) -join ''))
+    }
+    [void]$builder.Append('"')
+    return $builder.ToString()
+}
+
+function Set-AnswerMeProcessArguments {
+    param(
+        [Parameter(Mandatory = $true)]
+        [System.Diagnostics.ProcessStartInfo]$StartInfo,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [object[]]$Arguments
+    )
+
+    $encoded = @($Arguments | ForEach-Object {
+        ConvertTo-AnswerMeWindowsProcessArgument -Value ([string]$_)
+    })
+    $StartInfo.Arguments = [string]::Join(' ', [string[]]$encoded)
+}
+
+function Set-AnswerMeProcessEnvironmentVariable {
+    param(
+        [Parameter(Mandatory = $true)]
+        [System.Diagnostics.ProcessStartInfo]$StartInfo,
+        [Parameter(Mandatory = $true)]
+        [string]$Name,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string]$Value
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Name) -or $Name.IndexOf('=') -ge 0 -or $Name.IndexOf([char]0) -ge 0) {
+        throw 'Process environment variable name is invalid.'
+    }
+    if ($Value.IndexOf([char]0) -ge 0) {
+        throw 'Process environment variable value cannot contain a null character.'
+    }
+    $StartInfo.EnvironmentVariables[$Name] = $Value
+}

package/distribution/npm/skills/ask-when-needed/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: ask-when-needed
+description: 每个任务开始实质工作前必须加载，检查工作目标和必要前置条件是否齐全；任务中目标、约束、证据或用户要求发生实质变化时重新检查。判断默认处理、调查或提问，组织开工核对与访谈，选择渠道并恢复原任务。加载不意味着必须提问，也不把每次普通回复当成新任务。
+---
+
+# AskWhenNeeded
+
+## 目标
+
+在工作开始前检查需求理解，在执行中根据新信息更新。区分必要澄清与可选复核，避免遗漏和过度打断；根据问题形态选择访谈策略与渠道，获得答复后恢复原任务。
+
+本 Skill 是用户输入的临时路由器，不是原任务的流程控制器。需求、设计、实现、调试、审批或其他专项工作仍由调用它的任务或 Skill 控制。
+
+## 遵守边界
+
+- 遵守当前环境的指令优先级、授权、安全、文件保护与持久化规则。本 Skill 不扩大权限。
+- 不用提问代替合理调查，也不为避免一次低成本确认而无限调查。
+- 不把任何具体 Skill、工具、MCP、网页服务或 Agent 产品设为默认渠道，也不要求为了提问而安装特定能力。
+- 访谈策略只定义如何询问，不接管原任务，也不自行决定具体交互工具。
+- 未回答、取消或超时均不表示同意。
+
+## 识别检查节点
+
+- 每个任务开始实质工作前，围绕当前交付物检查目标、验收标准、必要输入、约束和授权；不等发现缺口才加载。
+- 只整理已有信息的缺口、冲突，以及下一步实际依赖的条件；不穷举假想分歧，不为凑题重复已确认内容。
+- 目标、约束、证据或用户要求发生实质变化时重新检查；进入重要决策、外部操作或最终结论前，核对所依赖的条件是否仍有效。
+
+检查节点不单独构成提问理由。没有具体缺口、有价值的可选核对问题或明确访谈请求时，继续原任务；普通回复不重新开启一次开工检查。
+
+## 判断是否值得提问
+
+先查当前任务明确指向的代码、规格、配置、日志、文档和其他可用证据，再查最接近问题的权威、直接、当前版本来源。来源冲突时，不把找到单个来源视为已经查明。
+
+下一次调查不能明显提高结论可靠度，或调查成本已经高于一次用户确认时，停止追加调查。
+
+用户明确要求 Brainstorm 或 Grill 时，该请求构成采用相应访谈策略的理由，不要求额外证明存在既定未决事实；但访谈中的事实性问题仍必须先调查，范围扩展和策略切换仍需确认。
+
+- **已有有效答案**：当前指示、已确认信息或适用约定已决定做法，且没有反证时直接沿用。
+- **能够可靠查明**：在当前授权和合理成本内先调查或验证；来源冲突未解决不算查明。
+- **不同答案不会实质改变结果**：按适用惯例选择成本较低的默认做法，必要时说明假设。
+- **有实质影响且无法合理查明**：进入时点判断，向用户收集答案。
+
+实质影响指不同答案会改变目标、验收标准、范围、授权边界，或造成显著返工；架构、数据、安全和用户专属选择按这些后果判断。可逆性只用于评估执行风险，不能单独作为默认处理的理由。
+
+## 开工前核对
+
+- **可选复核**：必要条件齐全且存在有价值的核对问题时，说明核对原因和预计题数，邀请用户核对或直接开始；复杂题组的申请按“访谈申请与轮次变化”执行，不再叠加一次申请。
+- **无需重复申请**：已有明确开工指示、讨论已经充分或没有具体问题时，直接开始。用户拒绝可选复核后，沿用已确认信息推进。
+- **必要澄清**：说明具体缺口及其影响，单个简单问题直接问，复杂题组先申请。拒绝访谈不表示条件已补齐；只继续不受缺口影响的工作。
+
+## 选择提问时点
+
+“决策锁定点”是第一个依赖该答案，并会锁定重要方向、产生显著返工、造成外部影响或变得难以恢复的步骤。
+
+- **已到决策锁定点**：现在问；高影响或不可逆操作在执行前取得明确同意。
+- **尚未到决策锁定点**：记录待决问题，继续不受影响的工作，在锁定点前提问。
+- **低成本证据即将获得**：先完成验证，再决定是否提问。
+- **新证据推翻旧答案或假设**：重新判断，不机械沿用旧结论。
+
+不要先执行依赖答案的工作，再用提问追认本可提前确认的假设。
+
+## 选择访谈策略
+
+策略与渠道是两个独立维度。先选择如何访谈，再选择通过什么能力交付。
+
+- **直接提问**：单个明确缺口、简单确认、单选或简短开放回答。保持轻量，不加载访谈参考。
+- **Brainstorm**：问题开放复杂、候选空间尚未形成，或需要先发散再归类、比较和收拢。选择后读取 [references/interview-strategies.md](references/interview-strategies.md) 的 Brainstorm 部分。
+- **Grill**：已有计划、方案或决策框架，需要暴露关键矛盾、验证依赖并锁定落地细节。选择后读取同一参考的 Grill 部分。
+
+用户明确指定策略时，在不违反更高优先级约束的前提下保持该选择。策略不再适合时，说明新策略、切换原因和收益；获得用户确认后切换。Brainstorm 收拢出候选方案后可以转入 Grill，Grill 发现尚无可行解空间时可以转回 Brainstorm。
+
+旧的显式兼容入口只能提供策略提示；本 Skill 仍负责最终路由。不得反向加载兼容入口。
+
+## 设计问题
+
+- 每题只问一个核心判断；用最少背景说明问题及其具体影响。
+- 需要选项时，使其简短、可执行并保留自由输入；单选项应互斥，多选项可组合。
+- 协助用户理清思路或作方案取舍时，默认先结合已知目标、事实和约束形成推荐，说明关键理由、主要代价和适用条件，再请用户确认或修正；保留可行替代与自由表达，不把可以完成的分析转嫁给用户，也不以开放题代替应有的建议。
+- 依据不足时先作合理调查；仍缺关键条件时给出条件性建议，并只追问会改变建议的缺口。无法形成有依据的推荐时说明缺口，提供判断框架，不捏造事实、确定性或优劣。
+- 按每道题判断是否需要中立：核实实际情况、采集真实经历或未经引导的偏好，以及调查、测量等会被建议污染的回答，不预设推荐答案，可提供中立的说明或示例。不能仅因用户尚未形成偏好就免除决策辅助；推荐不等于用户答案或操作授权。
+- 每轮最多 3 题，优先解决最重要的上游问题；相互依赖的问题分轮，独立问题可以同轮。不把多个判断藏进一题以规避上限。
+- 每轮获得答案后更新已知信息，删除已解决或失去价值的问题，重新组织后续高价值问题；不问满配额。
+- 简单确认保持简单，不为使用丰富界面而增加步骤。
+- 选择 Brainstorm 或 Grill 时，问题内容与顺序服从访谈参考；是否组成题组仍由本 Skill 结合依赖关系和渠道能力决定。
+
+## 按能力选择渠道
+
+**简单问题**：当前待问内容只有一道单选题，且题干不超过 20 字。独立背景与选项不计入题干；不得把实际问题移进背景、删减必要信息或硬改成单选来规避分流。其他均为**非简单（复杂）问题**，包括多选、多道题及开放式问题。按当前已知的整组待问内容判断，不因分轮投递降为简单问题；访谈管理确认按下一节单独处理。此分类只用于渠道分流，不表示认知难度、业务重要性或风险。
+
+| 输入需要 | 必要能力 |
+|---|---|
+| 简单问题 | 单选与必要背景展示 |
+| 开放式问题 | 自由文本 |
+| 多项同时选择 | 真正多选 |
+| 多个相关问题或丰富说明 | 结构化题组和上下文展示 |
+| 用户可能稍后回答 | 异步等待和任务恢复 |
+| 用户可能更换设备 | 跨设备访问 |
+| 高影响操作 | 明确确认和所需的可追溯性 |
+
+1. 检查当前真实可用的能力，不假定平台一定支持多选、异步或跨设备。
+2. 用户明确指定渠道时，在能力、安全和授权允许的前提下保持该选择；访谈策略不得改写渠道决定。
+3. 当前环境存在范围匹配且已获授权的首选渠道策略时，在满足必要能力、能够安全承载当前内容且授权充分的候选中优先采用；不能满足时明确说明降级或阻塞，不得假装已经使用成功。
+4. 不存在适用的首选渠道策略时，在满足必要能力的渠道中选择启动步骤、等待时间和用户操作最少者。
+5. 缺少的能力只是便利时，允许降级并说明损失。
+6. 能力是用户明确要求或正确收集答案的必要条件时，不得声称普通对话已经满足；说明阻塞，并请求更换渠道或输入形式。
+
+首选渠道只改变渠道排序，不扩大授权，也不替代高影响操作所需的独立确认。策略范围不匹配、内容不适合该渠道或渠道不可用时，继续按必要能力选择其他低成本渠道。
+
+## 访谈申请与轮次变化
+
+- 复杂提问开始前，说明为什么提问、预计总题数和最多轮数，再用一道简单单选申请开始；必要背景独立展示。按渠道规则交付该申请，不再为交付申请本身递归申请。
+- 用户已明确要求开始访谈或逐项审批且范围明确时，该请求视为启动同意；说明题数和轮数后开始，不重复确认。访谈同意不授权业务执行或高风险操作。
+- 保留获准话题范围、题数和轮数上限，以及已用题数和轮数。原范围和上限内可以动态重排问题；超出范围、题数或轮数前，说明新增缺口、影响及新增上限，重新申请。
+- 信息提前充分时，说明必要条件已澄清，请用户确认是否提前结束访谈并开始工作；未收到同意前，不擅自提前结束，也不为补足轮数继续凑题。用户明确停止时立即停止，无需追问是否停止。
+- 按约定完成时恢复原任务；拒绝追加、取消或未答均不补齐缺口，只推进不依赖该答案的工作。启动与轮次变更的管理确认不占已获准的内容题数和轮数，避免确认本身触发追加申请。
+
+## 等待与恢复
+
+提问前保留四项最小状态：待决问题、第一个受影响步骤、已完成且无需重做的工作、等待期间仍可安全推进的工作。
+
+当结构化提问因超时、取消或返回空答案而未收到用户有效回复，导致本轮等待中断时，最终回复必须完整复述决策背景、待决问题、全部候选项及各自关键后果；不得假定用户已经看过或仍能看到问卷，不得省略上述信息而直接要求用户“批准”“确认”或“继续”。
+
+获得答复后：
+
+1. 将答复映射到待决问题；存在歧义时只澄清该歧义。
+2. 更新相关假设和计划，不重复询问已经回答的事项。
+3. 访谈尚未结束时按轮次规则继续；结束条件及所需确认满足后，从第一个受影响步骤恢复，不无故重做已完成工作。
+4. 取消、超时或未回答时，只继续不依赖答案且安全的工作；否则说明阻塞点。
+
+## 从纠正中提出候选偏好
+
+以下信号可以触发偏好建议：用户明确说“以后”“每次”“不要再”；同类默认行为被重复否定；纠正反映稳定工作方式、授权边界或风险偏好；不记录会持续产生显著返工或风险。
+
+一次特殊情况、普通方案选择、临时环境偏好、无法写清条件的纠正，以及用户已拒绝且没有新证据的同类规则，只用于当前任务。
+
+候选规则写清：触发条件、行为、范围、例外、建议载体。可以这样询问：
+
+```text
+你刚才否定了我在“[触发条件]”时默认“[原行为]”。
+以后遇到这类情况，要不要先向你确认“[需要确认的信息]”？
+建议范围：[范围]；例外：[例外]。
+```
+
+## 经同意后持久化
+
+- 未经明确同意，只在当前会话应用纠正，不写入文件或外部记忆。
+- 按当前环境的全局持久化规则选择最小权威载体：项目偏好写项目规则，跨项目个人偏好写用户级规则；个人偏好不得写入核心 `SKILL.md`。
+- 只有方法本身的通用变化，才可在用户明确授权修改该 Skill 后写入核心 `SKILL.md`。
+- 写入前说明具体规则、范围和目标路径并取得所需授权；写入后回读。失败时明确说明不具备跨会话约束力。
+- 不持久化密钥、身份信息、私人答案或其他敏感内容。撤销或收窄规则时遵循相同授权流程。
+
+## 应用偏好
+
+- 只应用范围与当前情境匹配的规则；当前任务的明确指示优先，但不能覆盖更高优先级指令或安全边界。
+- 项目规则不得外推为跨项目偏好；规则冲突或范围不清时询问用户。
+- 不因存在偏好而机械提问，触发条件不成立时继续正常工作。
+
+## 自检
+
+提问前核对：必要澄清、可选复核或显式访谈的依据成立；合理调查已到停止线；提问时点、访谈同意与轮次范围符合上述规则；已提供有依据的决策建议，或有明确的中立需要或证据缺口；问题单义，渠道符合适用策略并满足必要能力。
+
+必要能力缺失而阻塞时，回答同时说明缺失能力、受阻步骤，并明确请求更换渠道、恢复能力或放宽输入要求。
+
+建议持久化前确认：这是稳定模式而非一次例外；规则、范围和例外具体；用户明确同意；载体符合当前环境的全局规则。

package/distribution/npm/skills/ask-when-needed/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ask When Needed"
+  short_description: "开工前检查目标与前置条件，区分默认处理、必要澄清和可选核对"
+  default_prompt: "使用 $ask-when-needed 在实质工作前检查目标与必要条件，判断默认处理、调查或提问，按获准范围组织访谈并恢复任务。"

package/distribution/npm/skills/ask-when-needed/references/interview-strategies.md

@@ -0,0 +1,43 @@
+# 访谈策略
+
+仅当 `ask-when-needed` 已选择 Brainstorm 或 Grill 时读取。本参考只定义访谈方法和切换信号；是否提问、题组组织、渠道、等待与恢复仍由 `ask-when-needed` 决定。
+
+## 共享状态
+
+维护：当前策略、主题与范围、已确认信息、未确定信息、问题路径、已解决与未解决分支、获准与已用题数和轮数、停止条件、待恢复位置。启动、追加和提前结束的确认统一遵循 `ask-when-needed` 的“访谈申请与轮次变化”，本参考不另设结束权限。
+
+- 证据、自洽性、可行性和实际约束优先于迎合。
+- 发现跑题、理解偏差、无法继续求真或问题质量下降时暂停，说明原因并交回路由器判断下一步。
+- 用户停止时立即停止。强调深挖或拷问不表示无限循环。
+
+## Brainstorm
+
+目标：先扩大候选空间，再把想法归类、比较、筛选并收拢为可判断的结论或下一步。
+
+1. 开始前确定主题与重点方向，按路由器规则取得启动同意并维护题数和轮数上限。
+2. 题组组织遵守路由器的每轮上限与依赖顺序，不将上限当成必须问满的配额。
+3. 发散阶段探索彼此不同的方向、约束和反例，不因首个可行想法过早收敛。
+4. 根据最新答案动态生成下一问题；不预先倾倒完整清单，不重复用户已回答的内容。
+5. 新的深度分支超出当前范围或需要追加题数、轮数时，交回路由器申请后再扩展。
+6. 收拢阶段合并重复想法，按目标、证据、约束、成本和风险比较候选；淘汰不满足资格或缺少执行路径的候选。
+7. 信息足够时交回路由器处理结束或提前结束确认；达到上限不得自行追加。结束时总结已确认、未确定、被淘汰方向、风险和下一步。
+
+### 转向 Grill 的信号
+
+候选方案或计划已经形成，继续发散的收益低于验证关键矛盾、依赖和落地细节的收益。将信号交回 `ask-when-needed`，不得自行切换。
+
+## Grill
+
+目标：从上游决策与关键矛盾开始，逐分支验证计划，直到结论自洽且落地细节足够明确。
+
+1. 按决策依赖建立问题树，维护已解决分支、未解决分支和下一个上游问题。
+2. 问题形式与推荐条件遵循 [问题设计规则](../SKILL.md#设计问题)。
+3. 能从现有证据可靠查明的事实交回 `ask-when-needed` 先调查，不向用户转嫁。
+4. 沿依赖顺序推进；新答案改变上游前提时，重排未解决分支。
+5. 长轮次设置检查点，简述已解决、未解决、当前关键矛盾和下一问题。
+6. 用户停止时立即停止；达到共同理解、所有实质分支已解决、问题质量下降或继续提问收益不足时，交回路由器判断结束或申请提前结束；需要扩展时同样由路由器申请。
+7. 结束时总结共同结论、仍有分歧的分支、关键矛盾、风险和下一步。
+
+### 转向 Brainstorm 的信号
+
+当前阻塞不是某项决策未明确，而是缺少可行候选或问题空间尚未展开。将信号交回 `ask-when-needed`，不得自行切换。

package/lib/npm-cli/commands.mjs

@@ -0,0 +1,247 @@
+import path from 'node:path';
+import {
+  MACHINE_SCHEMA_VERSION,
+  MANAGED_SKILLS,
+  PACKAGE_VERSION,
+  publicCode,
+} from './constants.mjs';
+import { InstallerError, errorCode } from './errors.mjs';
+import {
+  discoverCodexHost,
+  evaluateManagedSkillDiscovery,
+} from './host-discovery.mjs';
+import {
+  classifyInstallation,
+  verifyPackageIntegrity,
+} from './package-integrity.mjs';
+import {
+  abortInstallTransaction,
+  executeInstallTransaction,
+  finalizeInstallTransaction,
+  recoverPendingTransaction,
+} from './transaction.mjs';
+import { runUsageValidation } from './usage-validation.mjs';
+
+export function checkRuntime({ platform = process.platform, arch = process.arch, nodeVersion = process.versions.node } = {}) {
+  if (platform !== 'win32' || arch !== 'x64') throw new InstallerError('unsupported-platform');
+  const match = String(nodeVersion).match(/^(\d+)\.\d+\.\d+(?:[-+].+)?$/);
+  if (!match || Number(match[1]) < 20) throw new InstallerError('node-version-unsupported');
+  return true;
+}
+
+function baseResult(command) {
+  return {
+    schemaVersion: MACHINE_SCHEMA_VERSION,
+    command,
+    version: PACKAGE_VERSION,
+    installation: { status: 'blocked', code: 'transaction-failed', directory: null, migratedFrom: null },
+    usageValidation: { status: 'not-run', code: null, cleanupWarning: null },
+    rollback: { status: 'not-needed', code: null },
+    host: null,
+    limitations: [],
+  };
+}
+
+function setHost(result, host) {
+  result.host = { id: 'codex', version: host.hostVersion };
+  result.installation.directory = host.skillsRoot;
+}
+
+function dependency(name, fallback, dependencies) {
+  return dependencies[name] ?? fallback;
+}
+
+async function discover(input, dependencies) {
+  const discoverHost = dependency('discoverHost', discoverCodexHost, dependencies);
+  return discoverHost(input, dependencies.host ?? {});
+}
+
+async function prepare(command, options, dependencies) {
+  checkRuntime(dependencies.runtime);
+  const packageVerifier = dependency('verifyPackage', verifyPackageIntegrity, dependencies);
+  const packageInfo = await packageVerifier(dependencies.packageOptions);
+  let host = await discover({ cwd: options.cwd, env: options.env, context: options.executionContext }, dependencies);
+  const recover = dependency('recoverTransaction', recoverPendingTransaction, dependencies);
+  const recovered = await recover(host, dependencies.transaction ?? {});
+  if (recovered.status !== 'none') {
+    host = await discover({ cwd: options.cwd, env: options.env, context: options.executionContext }, dependencies);
+  }
+  evaluateManagedSkillDiscovery(host, { requireInstalled: false });
+  const classify = dependency('classifyInstallation', classifyInstallation, dependencies);
+  const classification = await classify(host.skillsRoot, packageInfo);
+  return { command, packageInfo, host, classification, recovered };
+}
+
+async function verifyAfterMutation(context, dependencies, { absent = false } = {}) {
+  const observed = await discover({
+    cwd: context.options.cwd,
+    env: context.options.env,
+    context: context.options.executionContext,
+  }, dependencies);
+  if (path.resolve(observed.codexHome) !== path.resolve(context.host.codexHome)
+    || path.resolve(observed.skillsRoot) !== path.resolve(context.host.skillsRoot)) {
+    throw new InstallerError('codex-root-untrusted');
+  }
+  evaluateManagedSkillDiscovery(observed, absent ? { requireAbsent: true } : { requireInstalled: true });
+  return observed;
+}
+
+async function invokeUsageValidation(skillsRoot, dependencies) {
+  const validateUsage = dependency('validateUsage', runUsageValidation, dependencies);
+  return validateUsage({ skillsRoot, timeoutSeconds: 300 }, dependencies.usage ?? {});
+}
+
+async function installOrUpdate(command, options, dependencies) {
+  const result = baseResult(command);
+  const prepared = await prepare(command, options, dependencies);
+  prepared.options = options;
+  setHost(result, prepared.host);
+  result.installation.migratedFrom = prepared.classification.legacyVersion ?? null;
+
+  if (command === 'update' && prepared.classification.kind === 'absent') {
+    throw Object.assign(new InstallerError('not-installed'), { partialResult: result });
+  }
+
+  let transactionHandle = null;
+  if (prepared.classification.kind === 'current') {
+    await verifyAfterMutation(prepared, dependencies);
+    result.installation.status = 'completed';
+    result.installation.code = 'no-change';
+  } else {
+    const transact = dependency('executeTransaction', executeInstallTransaction, dependencies);
+    const transaction = await transact({
+      operation: command,
+      codexHome: prepared.host.codexHome,
+      skillsRoot: prepared.host.skillsRoot,
+      packageInfo: prepared.packageInfo,
+    }, { ...(dependencies.transaction ?? {}), deferFinalize: true });
+    if (transaction.status === 'failed') {
+      result.installation.status = 'failed';
+      result.installation.code = publicCode(transaction.code);
+      result.rollback = { status: 'completed', code: 'rollback-completed' };
+      return { exitCode: 1, result };
+    }
+    transactionHandle = transaction.transactionHandle;
+    try {
+      await verifyAfterMutation(prepared, dependencies);
+      const finalize = dependency('finalizeTransaction', finalizeInstallTransaction, dependencies);
+      const finalized = await finalize(transactionHandle);
+      result.installation.status = 'completed';
+      result.installation.code = 'ok';
+      if (finalized.cleanupWarning) result.limitations.push('cleanup-warning');
+    } catch (error) {
+      const abort = dependency('abortTransaction', abortInstallTransaction, dependencies);
+      try {
+        await abort(transactionHandle, dependencies.transaction ?? {});
+        result.installation.status = 'failed';
+        result.installation.code = errorCode(error);
+        result.rollback = { status: 'completed', code: 'rollback-completed' };
+        return { exitCode: 1, result };
+      } catch {
+        result.installation.status = 'recovery-required';
+        result.installation.code = 'recovery-required';
+        result.rollback = { status: 'recovery-required', code: 'recovery-required' };
+        return { exitCode: 2, result };
+      }
+    }
+  }
+
+  const usage = await invokeUsageValidation(prepared.host.skillsRoot, dependencies);
+  result.usageValidation = usage;
+  if (usage.cleanupWarning) result.limitations.push('cleanup-warning');
+  return { exitCode: 0, result };
+}
+
+async function uninstall(options, dependencies) {
+  const command = 'uninstall';
+  const result = baseResult(command);
+  const prepared = await prepare(command, options, dependencies);
+  prepared.options = options;
+  setHost(result, prepared.host);
+  if (prepared.classification.kind === 'absent') {
+    result.installation.status = 'completed';
+    result.installation.code = 'no-change';
+    return { exitCode: 0, result };
+  }
+  if (prepared.classification.kind === 'current-unowned') {
+    throw Object.assign(new InstallerError('not-installed'), { partialResult: result });
+  }
+  const transact = dependency('executeTransaction', executeInstallTransaction, dependencies);
+  const transaction = await transact({
+    operation: command,
+    codexHome: prepared.host.codexHome,
+    skillsRoot: prepared.host.skillsRoot,
+    packageInfo: prepared.packageInfo,
+  }, { ...(dependencies.transaction ?? {}), deferFinalize: true });
+  if (transaction.status === 'failed') {
+    result.installation.status = 'failed';
+    result.installation.code = publicCode(transaction.code);
+    result.rollback = { status: 'completed', code: 'rollback-completed' };
+    return { exitCode: 1, result };
+  }
+  try {
+    await verifyAfterMutation(prepared, dependencies, { absent: true });
+    const finalize = dependency('finalizeTransaction', finalizeInstallTransaction, dependencies);
+    const finalized = await finalize(transaction.transactionHandle);
+    result.installation.status = 'removed';
+    result.installation.code = 'removed';
+    if (finalized.cleanupWarning) result.limitations.push('cleanup-warning');
+    return { exitCode: 0, result };
+  } catch (error) {
+    const abort = dependency('abortTransaction', abortInstallTransaction, dependencies);
+    try {
+      await abort(transaction.transactionHandle, dependencies.transaction ?? {});
+      result.installation.status = 'failed';
+      result.installation.code = errorCode(error);
+      result.rollback = { status: 'completed', code: 'rollback-completed' };
+      return { exitCode: 1, result };
+    } catch {
+      result.installation.status = 'recovery-required';
+      result.installation.code = 'recovery-required';
+      result.rollback = { status: 'recovery-required', code: 'recovery-required' };
+      return { exitCode: 2, result };
+    }
+  }
+}
+
+async function doctor(options, dependencies) {
+  const command = 'doctor';
+  const result = baseResult(command);
+  const prepared = await prepare(command, options, dependencies);
+  setHost(result, prepared.host);
+  if (prepared.classification.kind !== 'current') {
+    result.installation.status = 'checked';
+    result.installation.code = 'doctor-issue';
+    result.limitations.push(prepared.classification.kind === 'legacy' ? 'untrusted-legacy-installation' : 'not-installed');
+    return { exitCode: 1, result };
+  }
+  evaluateManagedSkillDiscovery(prepared.host, { requireInstalled: true });
+  result.installation.status = 'checked';
+  result.installation.code = 'doctor-healthy';
+  if (options.interactive) result.usageValidation = await invokeUsageValidation(prepared.host.skillsRoot, dependencies);
+  return { exitCode: 0, result };
+}
+
+export async function runCommand(command, options = {}, dependencies = {}) {
+  const normalized = {
+    cwd: path.resolve(options.cwd ?? process.cwd()),
+    env: options.env ?? process.env,
+    executionContext: options.executionContext ?? {},
+    interactive: options.interactive === true,
+  };
+  try {
+    if (command === 'install' || command === 'update') return await installOrUpdate(command, normalized, dependencies);
+    if (command === 'uninstall') return await uninstall(normalized, dependencies);
+    if (command === 'doctor') return await doctor(normalized, dependencies);
+    throw new InstallerError('invalid-command');
+  } catch (error) {
+    const result = error.partialResult ?? baseResult(command);
+    const code = errorCode(error, 'transaction-failed');
+    result.installation.status = error?.recoveryRequired ? 'recovery-required' : 'blocked';
+    result.installation.code = code;
+    if (error?.recoveryRequired) result.rollback = { status: 'recovery-required', code: 'recovery-required' };
+    return { exitCode: error?.recoveryRequired ? 2 : 1, result };
+  }
+}
+
+export const __test = Object.freeze({ baseResult, prepare, verifyAfterMutation });