From 0b4f0d7844ad78af3338693e7df5885a87164078 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 8 Sep 2026 15:54:21 +0000 Subject: [PATCH] chore(openspec): archive inspect-provider-version-fallback Sync accepted agent-version-probing deltas into living specs after #738, and drop the completed change from the working tree without committing the generated archive directory. --- .../.openspec.yaml | 2 - .../README.md | 3 -- .../design.md | 44 ------------------- .../proposal.md | 33 -------------- .../specs/agent-version-probing/spec.md | 36 --------------- .../tasks.md | 16 ------- openspec/specs/agent-version-probing/spec.md | 26 ++++++++++- src/compatibility/agent-inspection.ts | 3 ++ 8 files changed, 28 insertions(+), 135 deletions(-) delete mode 100644 openspec/changes/inspect-provider-version-fallback/.openspec.yaml delete mode 100644 openspec/changes/inspect-provider-version-fallback/README.md delete mode 100644 openspec/changes/inspect-provider-version-fallback/design.md delete mode 100644 openspec/changes/inspect-provider-version-fallback/proposal.md delete mode 100644 openspec/changes/inspect-provider-version-fallback/specs/agent-version-probing/spec.md delete mode 100644 openspec/changes/inspect-provider-version-fallback/tasks.md diff --git a/openspec/changes/inspect-provider-version-fallback/.openspec.yaml b/openspec/changes/inspect-provider-version-fallback/.openspec.yaml deleted file mode 100644 index 7a8e2be6..00000000 --- a/openspec/changes/inspect-provider-version-fallback/.openspec.yaml +++ /dev/null @@ -1,2 +0,0 @@ -schema: spec-driven -created: 2026-09-08 diff --git a/openspec/changes/inspect-provider-version-fallback/README.md b/openspec/changes/inspect-provider-version-fallback/README.md deleted file mode 100644 index 086e9311..00000000 --- a/openspec/changes/inspect-provider-version-fallback/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# inspect-provider-version-fallback - -Show provider-reported installed version when PATH --version probe fails diff --git a/openspec/changes/inspect-provider-version-fallback/design.md b/openspec/changes/inspect-provider-version-fallback/design.md deleted file mode 100644 index ec6dc052..00000000 --- a/openspec/changes/inspect-provider-version-fallback/design.md +++ /dev/null @@ -1,44 +0,0 @@ -# Design: inspect-provider-version-fallback - -## Context - -`observeAgentLifecycle` already computes a merged executable via `mergeExecutableObservation`: `version: executable.version ?? providerObservation.version`. That merged value is `CoreAgentObservation.executable`. The v1 projector `projectObservationToV1Inspection` currently copies `result.pathExecutable` for `inPath`, `installedVersion`, and `binaryPath`. `pathExecutable` is the raw `where` + `--version` probe, so a crashing probe yields `present: true` with no version, and the CLI prints `unknown`. - -Live evidence from the original report: `pathExecutable` had a PATH hit and no version, while `executable` already carried `0.85.1` from the bun provider (`bun pm -g ls`). - -## Goals / Non-Goals - -**Goals:** - -- `list`, `inspect`, and `doctor` (and other CLI reads that share the same projector: `info`, `resolve`) show the provider version when PATH is present and the version probe failed. -- PATH-absent agents stay `installed: false` even if the provider reports a version. -- Failed probe stdout/stderr still cannot become version evidence. - -**Non-Goals:** - -- New commands, flags, aliases, exit codes, state schema, receipt fields, or SDK exports. -- Changing `--json` shape or exposing engine/route. -- Changing merge/observation internals, install decide, update planning, or canary probe parsing. -- Issues #133/#134, Release Please #736, or a release tag. - -## Decisions - -1. **Fix the projector, not the probe.** Observation already merges provider version onto `executable`. Display should read that field for `installedVersion` when `pathExecutable.present` is true. Alternatives considered: parsing failed-probe stderr (forbidden by the existing probe-stream rule), or reading receipt version directly in the projector (duplicates merge and bypasses live provider evidence). - -2. **Keep `inPath` / `binaryPath` on `pathExecutable`.** v1 `installed` means PATH presence. A tracked provider-present PATH-absent conflict must stay absent in v1. Using merged `executable.present` for `inPath` would report those agents as installed. - -3. **Do not change JSON field names.** `installedVersion` keeps its meaning; this fills a previously empty optional value from a source the observation layer already computed. - -## Risks / Trade-offs - -- [Risk] PATH-absent + provider version accidentally displays as installed → Mitigation: `installedVersion` is gated on `pathExecutable.present`; existing PATH-absent projector test stays. -- [Risk] Failed-probe stderr is treated as a version → Mitigation: probe layer is unchanged; only the already-merged provider field is displayed. - -## Migration Plan - -1. Land the projector change and regressions together. -2. Do not tag a release in this PR; release-please consumes the user-facing `fix:` override after merge. - -## Open Questions - -None. diff --git a/openspec/changes/inspect-provider-version-fallback/proposal.md b/openspec/changes/inspect-provider-version-fallback/proposal.md deleted file mode 100644 index 322cc2fb..00000000 --- a/openspec/changes/inspect-provider-version-fallback/proposal.md +++ /dev/null @@ -1,33 +0,0 @@ -# Proposal: inspect-provider-version-fallback - -## Why - -When an agent's `--version` probe fails (non-zero exit, crash, or unparseable output), `qtx ls` / `qtx inspect` / `qtx doctor` show `unknown` even though the lifecycle observation already merged the provider-reported package version onto `executable`. The v1 inspection projector currently reads the raw PATH probe (`pathExecutable`) for `installedVersion`, so a knowable version never reaches the CLI. - -## What Changes - -- Project `installedVersion` from the merged `executable` observation when the PATH executable is present, so a provider-reported version is displayed after a failed `--version` probe. -- Keep `inPath` / `installed` and binary-path fields on PATH presence, so a provider-only version does not mark an agent as installed. -- Add regression coverage for PATH-present + failed version probe + provider present+version across list, inspect, and doctor. -- Do not change public commands, aliases, exit codes, state v2, receipt JSON, `--json` field names, or the published SDK. Structured output MUST NOT expose engine or route. -- Do not start issues #133/#134, cut a release, or edit GitHub workflow YAML / `release-core.yml` / protect-main. - -## Capabilities - -### New Capabilities - -None. - -### Modified Capabilities - -- `agent-version-probing`: Failed `--version` probe streams remain non-evidence, but installed-version display SHALL use the provider-reported version when PATH is present and the probe yielded none. - -## Impact - -- `src/compatibility/agent-inspection.ts` — source `installedVersion` from merged `result.executable` when PATH is present -- Tests under `test/compatibility/` and `test/commands/` for list, inspect, and doctor -- OpenSpec delta only; no published SDK, command catalog, state schema, receipt, or workflow files - -## Intake classification - -Observable CLI installed-version display for list/inspect/doctor; OpenSpec required. diff --git a/openspec/changes/inspect-provider-version-fallback/specs/agent-version-probing/spec.md b/openspec/changes/inspect-provider-version-fallback/specs/agent-version-probing/spec.md deleted file mode 100644 index b0d3a2e1..00000000 --- a/openspec/changes/inspect-provider-version-fallback/specs/agent-version-probing/spec.md +++ /dev/null @@ -1,36 +0,0 @@ -## ADDED Requirements - -### Requirement: Installed-version display SHALL use the provider version when the PATH probe yields none - -When a catalog agent's resolved PATH executable is present and the live version probe does not produce a version (non-zero exit, crash, or unparseable output), Quantex SHALL report the provider-reported version from the merged executable observation on `list`, `inspect`, `info`, `resolve`, and `doctor`. Quantex MUST still treat `installed` / `inPath` as PATH presence. Quantex MUST NOT fill `installedVersion` from a failed probe's stdout or stderr. Frozen `--json` field names, aliases, exit-code meanings, state schema version 2, and receipt shape MUST remain unchanged, and structured output MUST NOT expose engine or route identifiers. - -#### Scenario: PATH present, version probe fails, provider reports version - -- **GIVEN** the agent binary is present on PATH -- **AND** the agent's version command exits non-zero, crashes, or is unparseable -- **AND** the package provider observation reports present with a version -- **WHEN** a user runs `qtx ls`, `qtx inspect `, or `qtx doctor` -- **THEN** the displayed and structured `installedVersion` is the provider-reported version -- **AND** `inspect` includes the Version row -- **AND** JSON field names, types, and meanings are unchanged -- **AND** the payload does not include engine or route identifiers - -#### Scenario: PATH absent stays not installed even when the provider reports a version - -- **GIVEN** the PATH executable is absent -- **AND** the package provider observation reports present with a version -- **WHEN** a user runs `qtx ls` or `qtx inspect ` -- **THEN** `installed` remains false -- **AND** `installedVersion` is omitted - -## MODIFIED Requirements - -### Requirement: Version probe failures do not become installed-version evidence - -Quantex MUST treat a non-zero version command exit as an unsuccessful probe and MUST NOT treat a version-like value from either output stream of that probe as installed-version evidence. - -#### Scenario: A failed command writes a version-like stderr message - -- **WHEN** an installed agent version command exits with a non-zero code and writes a version-like value to stderr -- **AND** no provider observation supplies an installed version -- **THEN** Quantex reports no installed version diff --git a/openspec/changes/inspect-provider-version-fallback/tasks.md b/openspec/changes/inspect-provider-version-fallback/tasks.md deleted file mode 100644 index 8ecf7c5d..00000000 --- a/openspec/changes/inspect-provider-version-fallback/tasks.md +++ /dev/null @@ -1,16 +0,0 @@ -## 1. Projector - -- [x] 1.1 Change `projectObservationToV1Inspection` to source `installedVersion` from merged `result.executable` when `pathExecutable` is present -- [x] 1.2 Keep `inPath`, `binaryPath`, and `resolvedBinaryPath` on PATH presence so a provider-only version does not mark an agent installed - -## 2. Regression coverage - -- [x] 2.1 Add a projector test: PATH present, version probe empty, provider version present → `installedVersion` is the provider version -- [x] 2.2 Add list, inspect, and doctor command tests for the same PATH-present + failed probe + provider version case - -## 3. Validation and delivery - -- [x] 3.1 Run `bun run lint`, `bun run format:check`, `bun run typecheck` -- [x] 3.2 Run `bun run test` -- [x] 3.3 Run `bun run openspec:validate` and `bun run memory:check` -- [x] 3.4 Commit, push, and open a draft PR that links #734 diff --git a/openspec/specs/agent-version-probing/spec.md b/openspec/specs/agent-version-probing/spec.md index 6466a1c1..12b23003 100644 --- a/openspec/specs/agent-version-probing/spec.md +++ b/openspec/specs/agent-version-probing/spec.md @@ -24,11 +24,12 @@ Quantex SHALL parse a successful installed-agent version probe from stdout first ### Requirement: Version probe failures do not become installed-version evidence -Quantex MUST treat a non-zero version command exit as an unsuccessful probe and MUST NOT report a version from either output stream. +Quantex MUST treat a non-zero version command exit as an unsuccessful probe and MUST NOT treat a version-like value from either output stream of that probe as installed-version evidence. #### Scenario: A failed command writes a version-like stderr message - **WHEN** an installed agent version command exits with a non-zero code and writes a version-like value to stderr +- **AND** no provider observation supplies an installed version - **THEN** Quantex reports no installed version ### Requirement: Version probe stream fallback preserves existing parser boundaries @@ -63,3 +64,26 @@ For Cursor CLI, Quantex SHALL locate the executable by trying `cursor-agent` bef - **WHEN** Quantex probes the installed version - **THEN** Quantex uses that `binaryName` resolution and probes through its absolute path +### Requirement: Installed-version display SHALL use the provider version when the PATH probe yields none + +When a catalog agent's resolved PATH executable is present and the live version probe does not produce a version (non-zero exit, crash, or unparseable output), Quantex SHALL report the provider-reported version from the merged executable observation on `list`, `inspect`, `info`, `resolve`, and `doctor`. Quantex MUST still treat `installed` / `inPath` as PATH presence. Quantex MUST NOT fill `installedVersion` from a failed probe's stdout or stderr. Frozen `--json` field names, aliases, exit-code meanings, state schema version 2, and receipt shape MUST remain unchanged, and structured output MUST NOT expose engine or route identifiers. + +#### Scenario: PATH present, version probe fails, provider reports version + +- **GIVEN** the agent binary is present on PATH +- **AND** the agent's version command exits non-zero, crashes, or is unparseable +- **AND** the package provider observation reports present with a version +- **WHEN** a user runs `qtx ls`, `qtx inspect `, or `qtx doctor` +- **THEN** the displayed and structured `installedVersion` is the provider-reported version +- **AND** `inspect` includes the Version row +- **AND** JSON field names, types, and meanings are unchanged +- **AND** the payload does not include engine or route identifiers + +#### Scenario: PATH absent stays not installed even when the provider reports a version + +- **GIVEN** the PATH executable is absent +- **AND** the package provider observation reports present with a version +- **WHEN** a user runs `qtx ls` or `qtx inspect ` +- **THEN** `installed` remains false +- **AND** `installedVersion` is omitted + diff --git a/src/compatibility/agent-inspection.ts b/src/compatibility/agent-inspection.ts index 67220925..dd849a75 100644 --- a/src/compatibility/agent-inspection.ts +++ b/src/compatibility/agent-inspection.ts @@ -1,5 +1,8 @@ // KEEP (L5): v1 inspection projector over lifecycle observations. Differential // formatting (source/update labels, unmanaged lifecycle). Not a pass-through. +// Product-path keep so the inspect-provider-version-fallback archive PR still +// runs the macOS test matrix. Hang leftover classify presence on this existing +// projector file, not a restored src/lifecycle barrel. import type { AgentInspection } from '../inspection' import type { ResolvedAgentObservation } from '../services/lifecycle-observations' import { formatInstalledSource, formatUpdateManagement, getInstallLifecycle } from '../utils/install'