[houlianpi]

Summary

Add a lightweight Quick Test entry alongside FSQ Case Manager, reusing the existing settings, environment diagnosis, execution, evidence, and reporting services rather than introducing another execution engine.

Draft / pending review, not final acceptance. F009 remains OPEN and UNWAIVED: canonical CI now passes, including clean locked npm installation and the configured package/isolated-venv/CLI smoke checks. Import/static smoke still lacks an installed-package origin assertion, and Twine has not run. Manual acceptance of the Android UI and green CI are not a waiver.

This PR contains exactly 99 feature paths. Six unrelated local workflow-control maintenance paths were deliberately excluded and left uncommitted.

Related issue

No issue was opened. This maintainer-requested work was authorized and confirmed directly through /spec-driven, and the maintainer authorized publication. No issue closure is claimed or fabricated.

Design document

No separate design document was used. The repository's current SDD workflow supports an explicit direct-project-change request followed by confirmation of the required SPEC updates before implementation; that is the route used here. This is feature work, not a behavior-preserving bug fix or a documentation/repository-metadata exception. The narrower exceptions named in the preserved template comment do not describe this chosen route. Confirmed root and module SPEC files, not an informal design document, were the implementation authority.

SPEC updates

The applicable SPEC deltas were confirmed before their corresponding implementation batches. All 13 changed root/module SPEC files included in this commit are:

• Root SPEC
• Control Plane frontend
• Agent Engine
• AI Services
• Application
• CLI
• Config
• Control Plane backend
• Environments
• Environment Providers
• Execution
• Models
• Providers

The unchanged frontend and adapter umbrella SPEC files were also part of the reviewed authority inputs.

Changes

• Add the Quick Test / Case Manager entry chooser and a lightweight exploration-only UI with shared Settings. Preserve Case Manager workflows, report links, Strict Replay, and navigation guards.
• Prepare one dedicated registered Quick Test Workspace using existing Config/Application ownership. Freeze each run's validated target; retain the shared single-active-task boundary and active-task restoration. Quick Test does not save Cases or introduce a separate public CLI test command.
• Reuse AI Services for tool-free intent analysis and Environments for concrete Android, Web, Windows, and macOS target validation. Preserve explicit Start, safe errors, and existing host/runtime restrictions; do not silently substitute targets or treat model output as readiness.
• Support explicit URL-free Web search goals without assuming a starting/result URL or adding a search service. Success requires actual current-Run Web capability activity and usable nonblank HTTP(S) browser observations; model-only claims are insufficient. This evidence gate is necessary, not proof that a discovered site is official.
• Show the Preparing workbench immediately and reuse the timeline, live evidence, and report surfaces. Keep connection notices quiet without concealing relevant execution state.
• For Android only, auto-select the sole current selectable device when no prior selection/clearing intent exists. Preserve manual identities and explicit clearing, retain device-scoped validation, and reject stale asynchronous restoration.
• Add and update regression tests, shared components/contracts, bilingual onboarding, and CLI documentation. No dependency, release-workflow, or agent-workflow maintenance changes are included.
• Follow-up commit d6a0d497 fixes only the native-path discovery test fixture: use a logical macOS reference with an exact, guarded mapping to the runner's temporary filesystem. Preserve all eight platform/provenance/existence combinations, the three result assertions, inventory guards, and real validator/plist processing. The recorded no-SPEC-delta decision restores verification of the existing root and Environments contracts; no production, SPEC, or CI change was needed.
• Follow-up commit 49e453f addresses the three review findings in six production/test files. A no-SPEC-delta decision was recorded before implementation because these repairs restore existing safe-projection, explicit-provenance, and path-only target contracts:
  • Sanitize the shared application display value with existing safe_text and secrets from frozen result.settings before task-state binding. Task/bootstrap/SSE application projections are safe; the execution URL and settings are unchanged. This is not a general goal-text redaction change.
  • Ground complete HTTP(S) tokens using the existing prose-punctuation policy, including the sentence-ending period example. Preserve the returned reference, native identifier boundaries, and protections against shortened host/path/query/fragment references, userinfo confusion, and embedded prefixes; add no normalization or retry.
  • Permit an absent CFBundleIdentifier key in a valid path-based macOS application candidate. Present null/empty/wrong-type/malformed values remain errors; exact bundle matching, cardinality, real filesystem/plist validation, no fallback, and the d6 cross-host fixture remain intact.

Verification

Current canonical CI: run 39225107945, on PR head 49e453f, completed successfully.

Job	Current result
Windows Server 2025 / CPython 3.13.16	3824 collected, 3824 passed; zero failures, skips, xfails, xpasses, or deselections
Ubuntu / CPython 3.11.17	3813 passed, 11 skipped
Ubuntu / CPython 3.13.16	3813 passed, 11 skipped
macOS / CPython 3.13.16	3813 passed, 11 skipped
Frontend Node 20	Vitest 4.1.11: 520 passed across 34 files
Frontend Node 22	Vitest 4.1.11: 520 passed across 34 files
Quality	SUCCESS
Package	SUCCESS
Required	SUCCESS

The Python matrix ran uv run --no-sync python -m pytest from the CI checkout ($GITHUB_WORKSPACE). The frontend jobs passed npm ci, npm run typecheck, npm test, npm run build:website, and npm run build. Quality passed Ruff lint/format checks; Package passed distribution build/rebuild, resource-contract checks, isolated-venv installation, and its configured smoke checks. All nine jobs, including Required, succeeded.

Latest three-comment repair verification: new focused tests first produced 23 actual failures and 65 passes against unchanged production code. The final combined check passed 371 tests:

uv run --no-sync python -m pytest tests/test_quick_test_transport.py tests/test_quick_test_intent.py tests/test_quick_test_discovery.py tests/test_quick_test_application.py tests/test_control_plane_history.py tests/test_macos_preflight.py -q --tb=short -rs

Ruff lint and format checks passed on all six edited files, as did git diff --check. A separate frozen-input full local Python run used:

uv run --no-sync python -m pytest -q --tb=short -rs

Result: 3813 passed, 11 Windows-specific skips, and one Google GenAI SDK deprecation warning on macOS/CPython 3.14.7. These local checks used isolated HOME/config/cache, UV_OFFLINE=1, existing dependencies, and no live Provider/device execution. The current CI matrix above subsequently verified the actual Windows result. Original failures, including corrected fixture/marker-format assertions and a lint finding, are retained locally rather than presented as additional product defects.

Earlier d6 fixture-only verification, retained as history: the fixture repair passed these local commands on macOS/CPython 3.14.7 before its publication, with isolated HOME/config/cache, UV_OFFLINE=1, and no installation:

uv run --no-sync python -m pytest tests/test_quick_test_discovery.py::test_native_path_references_never_fall_back_to_name_inventory -vv --tb=short -rs
uv run --no-sync python -m pytest tests/test_quick_test_discovery.py -q --tb=short -rs
uv run --no-sync ruff check tests/test_quick_test_discovery.py
uv run --no-sync ruff format --check tests/test_quick_test_discovery.py
git diff --check

Results at d6: 8 targeted parameters passed, 71 whole-file tests passed, and lint/format/whitespace checks passed. The pre-edit local target group also passed; the original four failures were on Windows CI. The earlier d6 CI run passed 3736 Windows tests; that historical result is distinct from the current 3824-test result above.

Original feature-publication local checks, retained as prior evidence:

Command	Result
npm test -- --reporter=dot	PASS: 520 tests across 34 files
uv run --no-sync ruff check .	PASS
uv run --no-sync ruff format --check .	PASS: 360 files already formatted
uv run --no-sync python -m pytest tests/test_uiautomator2_android_driver.py -q --tb=short -rs	PASS: 94 tests
git diff --cached --check	PASS before commit

These checks used the existing dependency environment, with UV_OFFLINE=1 and no sync/install. The targeted Python run used a fresh isolated HOME, USERPROFILE, XDG config/cache directories, and uv cache; it used fake device collaborators, not real Android hardware or private FSQ configuration.

Reused final focused evidence; not rerun merely for publication:

npm test -- frontend/control-plane/src/features/quick-test frontend/control-plane/src/api/quickTest.test.ts frontend/control-plane/src/api/quickDiagnostics.test.ts frontend/control-plane/src/app/EntryApp.integration.test.tsx frontend/control-plane/src/features/devices/hooks/useDeviceWorkspace.test.ts --reporter=dot
npm run typecheck
npm run build
git diff --check

Results: 188 focused tests across 9 files passed; typecheck, production build, and whitespace check passed. Publication identity checks established that their feature inputs remained unchanged.

Local browser-helper command, explicitly path-redacted:

.venv/bin/python <redacted-local-helper-directory>/android_selection_browser.py

That helper is not committed and the notation above is not a public reproducible checkout command. Existing production-bundle/mock-API checks passed at 1440x900, 1024x768, and 390x844 with 15 screenshots, trusted native keyboard clearing/reselection, zero console/page errors, and zero automatic POSTs. This is controlled browser evidence, not live Provider inference, real Android execution, or an actual screen-reader assessment.

Historical evidence, not current full-suite results:

• Earlier isolated-HOME full Python execution (.venv/bin/python -m pytest -q --tb=short -rs) recorded 3657 passed and 11 Windows-only skips at captured snapshot 42e6e4747902c96b4cdf1dcd990d86c593bbfac0. Subsequent changes include the canonical-main Android driver update, the d6 test-fixture repair, and the three-comment repair; use the current CI matrix above for current full-suite results.
• Earlier complete frontend testing recorded 432 passed; it is historical and superseded here by the current 520-test publication run. The preceding connection-notice batch's 145 tests are likewise not presented as a current full-suite result.

Warnings and incomplete verification:

• The earlier local environment used Vitest 4.1.10, while both manifest and lockfile specify 4.1.11. Current Node 20/22 CI completed clean locked installation and all 520 frontend tests with 4.1.11; the old local mismatch is not a current CI failure.
• Frontend tests retain Node localStorage experimental warnings and React act warnings. The reused production build has the existing large-chunk warning.
• F009 remains OPEN / UNWAIVED, with partial CI evidence: clean locked npm ci now passes. Package build/rebuild, resource checks, installation into an isolated venv, and both installed CLI --help commands also pass. However, the Python import/static smoke runs from the source checkout without asserting the imported package's origin, so it does not fully exclude source-tree shadowing. Twine metadata verification was not run by this CI workflow. The earlier local download/cache failures remain historical evidence; no blanket clean-installed-runtime pass or waiver is claimed.
• Canonical CI is green, but this does not establish completion of all release verification or close F009. The PR remains Draft.

Evidence

Committed regression references:

• Android selection and stale-response coverage
• Configuration-error identity recovery
• Quiet connection notices
• Entry and shared-workflow integration
• Quick Test preparation and validation
• Dynamic execution evidence regressions
• Host-independent native-path fixture and all eight parameters
• Safe application display through real HTTP task/bootstrap/SSE projections
• HTTP(S) punctuation, complete-reference preservation, and provenance rejection
• macOS missing-key, invalid-ID/metadata, and exact bundle-lookup regressions

The earlier one-file fixture repair passed a fresh independent pre-publication review. Its d6 Windows CI job records 71 passing tests in the discovery file and 3736 passing tests overall. The default pytest log is not a per-node verbose report: eight-parameter coverage is established by the exact checked-out test source, the unfiltered collection, and the absence of skips/xfails.

The subsequent three-comment repair passed independent local combined review before publication. Its current Windows CI job records 25 transport, 109 intent, and 103 discovery tests passing, within 3824 passing tests overall. The final CI evidence is handed back to the responsible Reviewer; updating this description does not reply to or resolve any review thread.

Prior independent full and repair reviews closed Quick Test findings F001-F008. The final Android selection request received an independent full review plus two automatic repair rounds, closing its four findings. F009 remains open; these reviews do not assert that unrelated workflow maintenance was audited for this PR.

Screenshots, raw logs, helper scripts, and review reports are retained locally and are not uploaded or committed. The committed configuration-error regression fixture was reviewed and uses a synthetic selected-device identity, not a real device identifier. No private session paths are published here.

The original feature publication matched its complete 611-blob capture, including 105 changed-source, 15 SPEC, and 21 context hash entries. Both follow-up post-audit captures checked all 611 files: d6 changed only the reviewed fixture file, and 49e453f changed only the six reviewed production/test files. Current CI checked out merge commit 1fe02dc866404e1bfd72fba4df5240f69dc53cb2; its entire tree equals the published 49e453f head's tree, and all six file blobs, modes, and SHA-256 identities match the reviewed freeze. The publication excludes the same six workflow-control changes; all six local working copies remain unchanged and unstaged.

Release or documentation impact

The English/Chinese READMEs and getting-started guides now explain the two browser entries, shared Settings, exploration-only Quick Test, model-resolved target validation, URL-free Web searches and their evidence limits, result/report handling, and when to use Case Manager. The CLI reference clarifies the fsq ui entry without adding a Quick Test CLI command.

No version bump, dependency update, release-workflow change, public media addition, merge, or release is included. Generated browser assets and distribution archives are not committed. Installed-package verification remains incomplete under F009 despite the passing configured CI checks, so this Draft PR is neither release approval nor a waiver.

Checklist

Spec-driven development

• I reviewed root SPEC.md and every relevant module SPEC.md.
• Any required design and SPEC confirmation gates occurred before implementation.
• The implementation, tests, and documentation agree with the current confirmed SPEC files.
• I used the current confirmed SPEC files, not the design document, as the implementation source of truth.

Quality and safety

• I ran focused tests and required formatting or lint checks, or explained why a check was not applicable.
• I updated user-facing documentation when behavior or setup changed, or it is not applicable.
• I did not commit credentials, tokens, account data, personal data, local .env files, generated logs, reports, screenshots, or workspace output.
• I reviewed any included screenshots, videos, logs, reports, and Run artifacts for secrets, private paths, device identifiers, and account data.
• I did not add large binary media to Git history unless the repository already owns that exact artifact and the size is justified.

[Copilot]

🟡 Changes recommended

Credential exposure and supported-input failures remain unresolved, while clean-install and package verification are still blocked.

3 open issues

• Redact URL credentials from application presentation values · New
• Handle sentence punctuation in explicit HTTP(S) references · New
• Allow path-based .app targets without CFBundleIdentifier · New

What changed in this PR

Adds Quick Test alongside Case Manager, reusing FSQ’s existing preparation, execution, evidence, and reporting services.

Changes:

• Adds an entry chooser, shared Settings, and an exploration-only workbench.
• Introduces target lookup, pending diagnostics, and evidence requirements for URL-free Web searches.
• Updates regression coverage, specifications, and bilingual onboarding.

File	Description
tests/​test_control_plane.py	Updates execution fixture.
tests/​test_application_doctor.py	Checks diagnostic serialization compatibility.
tests/​test_agent_engine_inference_paths.py	Covers Quick Test inference contracts.
README.zh-CN.md	Introduces Chinese Quick Test onboarding.
README.md	Introduces Quick Test onboarding.
fsq_agent/​providers/​SPEC.md	Clarifies intent-service ownership.
fsq_agent/​models/​SPEC.md	Documents lookup and pending facts.
fsq_agent/​models/​_platform_runtime.py	Adds pending prerequisite status.
fsq_agent/​models/​_application_lookup.py	Defines application lookup models.
fsq_agent/​models/​__init__.py	Exports lookup models.
fsq_agent/​execution/​SPEC.md	Defines Web search evidence requirements.
fsq_agent/​execution/​runs.py	Preserves evidence errors and redacts URL fragments.
fsq_agent/​execution/​dynamic.py	Enforces Web search evidence checks.
fsq_agent/​environments/​SPEC.md	Defines bounded application discovery.
fsq_agent/​environments/​providers/​SPEC.md	Documents platform lookup responsibilities.
fsq_agent/​environments/​providers/​_macos.py	Supports unresolved application diagnostics.
fsq_agent/​environments/​providers/​_applications.py	Implements platform application lookup.
fsq_agent/​environments/​providers/​_android.py	Adds explicit-selection and pending checks.
fsq_agent/​environments/​providers/​_adb_transport.py	Adds bounded package inventory.
fsq_agent/​environments/​_service.py	Exposes lookup and diagnostic context.
fsq_agent/​environments/​_applications.py	Bounds and normalizes discovery.
fsq_agent/​config/​SPEC.md	Documents exact-root creation and conflicts.
fsq_agent/​config/​_workspace.py	Adds exact-root workspace transactions.
fsq_agent/​config/​_user_provider.py	Classifies registry identity conflicts.
fsq_agent/​config/​_loader.py	Applies operator environment settings.
fsq_agent/​config/​__init__.py	Exports exact-root creation.
fsq_agent/​cli/​SPEC.md	Documents browser entry selection.
fsq_agent/​application/​workspace.py	Exposes Quick Test preparation.
fsq_agent/​application/​doctor.py	Supports pending-context diagnosis.
fsq_agent/​application/​contracts/​workspace.py	Defines Quick Test contracts.
fsq_agent/​application/​contracts/​shared.py	Adds Quick Test error codes.
fsq_agent/​application/​contracts/​doctor.py	Adds contextual diagnostic fields.
fsq_agent/​application/​contracts/​__init__.py	Exports new contracts.
fsq_agent/​application/​__init__.py	Exports Quick Test APIs.
fsq_agent/​ai_services/​SPEC.md	Defines intent-analysis behavior.
fsq_agent/​ai_services/​_quick_test.py	Implements structured intent analysis.
fsq_agent/​ai_services/​_factory.py	Constructs intent analyzers.
fsq_agent/​ai_services/​__init__.py	Exports intent services.
fsq_agent/​agent_engine/​SPEC.md	Includes Quick Test inference verification.
fsq_agent/​adapters/​control_plane/​_state.py	Tracks workflow and preparation identity.
fsq_agent/​adapters/​control_plane/​_server.py	Adds protected Quick Test endpoints.
fsq_agent/​adapters/​control_plane/​_readiness.py	Shares contextual readiness projections.
fsq_agent/​adapters/​control_plane/​_quick_test.py	Coordinates preparation and execution.
fsq_agent/​adapters/​control_plane/​_execution.py	Carries frozen preparation requirements.
fsq_agent/​adapters/​control_plane/​_evidence.py	Preserves safely redacted URLs.
frontend/​control-plane/​src/​test/​quickTestFixtures.ts	Supplies diagnostic fixtures.
frontend/​control-plane/​src/​test/​quick-test-android-config-error.json	Supplies configuration-error fixture.
frontend/​control-plane/​src/​styles/​devices.css	Styles pending diagnostics.
frontend/​control-plane/​src/​shared/​ContentTabs.tsx	Scopes keyboard focus to each tab set.
frontend/​control-plane/​src/​main.tsx	Mounts the entry chooser.
frontend/​control-plane/​src/​features/​quick-test/​useQuickTest.test.ts	Covers lifecycle and reconciliation.
frontend/​control-plane/​src/​features/​quick-test/​QuickTestPage.tsx	Adds setup and exploration workbench.
frontend/​control-plane/​src/​features/​quick-test/​QuickTestPage.configError.test.tsx	Covers selected-device error recovery.
frontend/​control-plane/​src/​features/​quick-test/​quick-test.css	Styles responsive Quick Test layouts.
frontend/​control-plane/​src/​features/​devices/​hooks/​useRunStream.test.ts	Covers Quick Test stream transitions.
frontend/​control-plane/​src/​features/​devices/​hooks/​useDeviceWorkspace.ts	Separates workflow restoration and busy state.
frontend/​control-plane/​src/​features/​devices/​hooks/​useDeviceWorkspace.test.ts	Covers cross-workflow reconciliation.
frontend/​control-plane/​src/​features/​devices/​DevicesPage.tsx	Handles entry activation and nullable identities.
frontend/​control-plane/​src/​features/​devices/​components/​RunTimeline.tsx	Shares pending source and Quick Test actions.
frontend/​control-plane/​src/​features/​devices/​components/​RunTimeline.test.tsx	Covers pending-source rendering.
frontend/​control-plane/​src/​features/​devices/​components/​PrerequisiteList.tsx	Displays pending prerequisites.
frontend/​control-plane/​src/​features/​devices/​components/​PrerequisiteList.test.tsx	Distinguishes prerequisite states.
frontend/​control-plane/​src/​features/​devices/​components/​PreflightStatus.tsx	Shares contextual environment checks.
frontend/​control-plane/​src/​features/​devices/​components/​PreflightStatus.test.tsx	Covers pending checks and scoped headings.
frontend/​control-plane/​src/​features/​devices/​components/​LiveEvidencePanel.tsx	Scopes evidence accessibility identifiers.
frontend/​control-plane/​src/​features/​devices/​components/​LiveEvidencePanel.test.tsx	Checks independent evidence-panel focus.
frontend/​control-plane/​src/​app/​shell/​navigation.ts	Defines Quick Test navigation.
frontend/​control-plane/​src/​app/​shell/​ControlPlaneShell.tsx	Supports both entry layouts.
frontend/​control-plane/​src/​app/​shell/​ControlPlaneShell.test.tsx	Checks unique shell identifiers.
frontend/​control-plane/​src/​app/​EntryApp.tsx	Coordinates entry routing and guards.
frontend/​control-plane/​src/​app/​EntryApp.test.tsx	Covers entry switching and state retention.
frontend/​control-plane/​src/​app/​entry.css	Styles chooser and return navigation.
frontend/​control-plane/​src/​app/​ControlPlaneApp.tsx	Preserves Manager state across entries.
frontend/​control-plane/​src/​app/​ControlPlaneApp.test.tsx	Checks inactive Settings teardown.
frontend/​control-plane/​src/​api/​types.ts	Adds workflow and diagnostic types.
frontend/​control-plane/​src/​api/​quickTest.test.ts	Validates Quick Test transport contracts.
frontend/​control-plane/​src/​api/​quickDiagnostics.test.ts	Validates contextual diagnostic responses.
frontend/​control-plane/​src/​api/​controlPlaneClient.ts	Adds Quick Test requests and validation.
frontend/​control-plane/​src/​api/​controlPlaneClient.test.ts	Updates workflow-aware snapshot coverage.
docs/​getting-started.zh-CN.md	Documents Chinese browser workflows.
docs/​getting-started.md	Documents browser workflows and evidence limits.
docs/​cli-reference.md	Clarifies fsq ui entry behavior.

_{Review effort: Balanced}

[houlianpi]

Addressed in 49e453f. The application display value now uses safe_text with configured_secret_values(result.settings) before shared-state binding, so projection uses the frozen secrets rather than rereading mutable configuration.

The HTTP regression checks task/bootstrap and active/terminal SSE application projections with synthetic query, fragment, and configured secrets, while asserting that the execution URL and settings remain unchanged. This does not introduce a general goal-text redaction policy.

CI run 39225107945 passed all nine jobs, including all 25 transport tests within 3824 passing Windows tests.

[houlianpi]

Addressed in 49e453f. HTTP(S) provenance now checks complete prompt URL tokens with the existing prose-punctuation policy; Open https://example.com. Verify its heading. accepts the explicit https://example.com reference without changing the returned value.

The regressions cover sentence punctuation, complete-reference preservation, and rejection of shortened host/path/query/fragment references, userinfo confusion, and embedded prefixes. Native identifier grounding remains unchanged; no URL normalization, upward Application import, or inference retry was added.

CI run 39225107945 passed all nine jobs, including all 109 intent tests within 3824 passing Windows tests.

[houlianpi]

Addressed in 49e453f. A valid path-based .app candidate may now omit the CFBundleIdentifier key. A present null, empty, wrong-type, or malformed identifier is still rejected, as are invalid plist/path facts.

The regressions cover explicit/inferred paths and exact bundle lookup: absent or different IDs cannot match, and no-fallback/cardinality checks remain. The existing host-independent fixture and its eight original combinations are preserved.

CI run 39225107945 passed the platform matrix, including all 103 discovery tests on Windows, Linux, and macOS; Windows completed 3824 tests without skips or xfails.