English | 简体中文
Status: implementation in progress. Scanning, platform adapters, presentation and CLI have source implementations; WinUI includes storage browsing, application registration browsing, cleanup review and history pages. v0.15.0 keeps public GUI/CLI cleanup, startup-task control, installer uninstall and privacy/storage removal gates closed; native adapters remain independently testable with generated fixtures. The release workflow builds unsigned, self-contained x64/ARM64 portable previews. Native fixture, installation and full UI/accessibility evidence is tracked in SYNC.md.
Shou for Windows uses C#, .NET 10 LTS and WinUI 3 from Windows App SDK. The GUI and CLI call the same C# domain services directly. Source editing and portable tests run on macOS; Windows builds and runtime checks run on Windows.
Use the repository shou-windows-cloud-test skill for Alibaba Cloud Wuying acceptance. Keep the desktop shut down with StopCharging during local development and UI alignment, then reuse it for concentrated native validation after local checks and synchronization packages are ready. Record the one-day retention deadline and continuing disk charges separately. Accounts, Keychain passwords and instance state remain in private local storage outside the repository.
| Need | Read |
|---|---|
| Architecture, project layout and implementation stages | Windows native implementation plan |
| Platform ownership and shared resources | Monorepo boundaries |
| Product and safety behavior | PRD, cleanup safety |
| Runtime, development and release sequences | Workflows and sequences |
| Feature parity and verification | SYNC.md |
| Structured diagnostics, regression layers and desktop E2E | Windows diagnostics and testing |
The first deliverable is a signed, self-contained WinUI shell on both x64 and ARM64, followed by a read-only scan and deterministic Core tests. Destructive capabilities require their own native acceptance before being enabled. See the plan for stage exit criteria.
Use the .NET SDK pinned by global.json. From the repository root:
python3 "scripts/generate-windows-resources.py" --check
sh "scripts/test-windows-core.sh"
sh "scripts/build-windows-cli.sh" win-arm64
sh "scripts/build-windows-cli.sh" win-x64The CLI build script stages unsigned self-contained development payloads in .build/windows/publish/<runtime>/cli. Cross-building does not establish Windows runtime or npm acceptance. The shared RID list in Directory.Build.props keeps lock files stable between host tests and architecture-specific restores.
On Windows, prepare the pinned .NET SDK and Python 3, and use a local output directory. The scripts default to %LOCALAPPDATA%/ShouBuild, outside the shared source:
./scripts/windows/test.ps1
./scripts/windows/build.ps1 -Runtime win-arm64 -Launch
./scripts/windows/build.ps1 -Runtime win-x64test.ps1 checks resources, runs Core/Presentation/native Platform/CLI tests, builds the CLI and runs generated-fixture contracts under an isolated data root. Windows CI runs x64 suites and both architecture builds, plus a separate Windows 11 ARM64 native suite/archive job. Both native architectures check CLI/WinUI startup and normal close. Every job must pass. Actual run results are recorded in SYNC.md; these suites do not replace complete ordinary-user desktop or physical-device acceptance.
Retained filesystem handles request data-read/directory-list access as well as metadata access so their share masks participate in native replacement and write protection. Privacy inspection explicitly permits shared writes on the final database/sidecar, while denying deletion. Metadata-only handles cannot provide this protection. Generated native fixtures explicitly assign the current-user owner and private inherited ACLs, including SQLite sidecars; elevated build-agent tokens can otherwise assign Administrators as the default owner. Production ownership and ACL checks remain strict.
Private-record publication uses NtSetInformationFile with FileRenameInformation and the retained parent handle. The Win32 rename wrapper rejects a non-null RootDirectory; no absolute-path fallback is used. The publication directory allows shared writes for NT destination opens while denying deletion/rename; the private mutation.lock serializes record operations. Existing native record-store cases verify replacement, reopened reads, private ACLs and competing leases.
Regenerate shared resources with python3 scripts/generate-windows-resources.py after changing their canonical sources. The generator records input/output digests and validates current translation placeholders. Design tokens in assets/design/tokens.json generate both WinUI Design.xaml and macOS ShouDesign.generated.swift; --check verifies both. WinUI consumes shared accent, spacing, radii, sidebar/titlebar dimensions and start-page typography, using two navigation groups, one toolbar and separate page states. Applications, startup items and history show details on demand. Rules support source/search filters and location-bound toggles; storage browsing provides a directory tree, extension totals and an area map. Settings save language, theme and reduced motion in current-user private atomic records; language changes rebuild the window. Windows still uses a native activity ring; exact Mac artwork, nested area maps and full visual/accessibility acceptance remain pending. See the design-resource contract.
Mac checks prove portable semantics and reference compilation. Windows tests, WinUI launch, signed installation and update checks require the matching native environments and separate evidence. The CLI's capabilities output owns actual availability. Rule-file reads require Windows and verify a regular local file without links, within 256 KiB and a ten-second deadline.
scripts/windows/test-uninstall-fixtures.ps1 is a separate native test entry; default tests install no software. Use native-architecture PowerShell 7.4 or later, the pinned .NET SDK and Python in a regular Windows 11 user session, with outputs on a local Windows disk:
& "./scripts/windows/test-uninstall-fixtures.ps1" -RunGeneratedMsiFixturesThis command explicitly opts the current process into fixture tests. It accepts no existing package, ProductCode or installation-location input. GeneratedMsiFixture creates an MSI from scratch using system Windows Installer APIs, with fresh ProductCode, PackageCode, UpgradeCode and component IDs. It installs one generated text file without custom actions, services, shortcuts or arbitrary uninstall commands. Per-user installation and the no-elevation summary flag constrain deployment. The destination deliberately contains Chinese characters and spaces; directory properties are supplied at runtime, keeping the database encoding neutral. The authored fallback destination is also a unique current-user directory rather than a volume root. Windows Installer still manages this generated product’s registration and cache.
Tests assemble test services directly, and their confirmation callback accepts only the current generated identity. They neither open the GUI/CLI execution gate nor change product confirmation. Coverage includes:
| Case | Native assertions |
|---|---|
| Successful uninstall | Discover the generated application from real registration, verify MSI context and PackageCode, execute with current confirmation/private journaling, then require installer success, original identity absence and removal of the registered file |
| Extra data and replay | Preserve hashes of unregistered generated data, the source and a protected sibling; rereading leaves records unchanged and the same plan cannot execute again |
| Declined confirmation | Keep the installation and bytes unchanged without execution intent |
| Installation removed after confirmation | Fixture-owned uninstall makes preflight reject without dispatching the adapter or writing intent |
| Changed actor and file use | Reject a different actor at the native boundary; holding the generated file blocks planning while preserving bytes |
| Mismatched registration clues | Different name, version, publisher or install directory yields no installation identity; exact clues still bind PackageCode and current-user context |
Cases run serially and require process-local SHOU_TEST_GENERATED_MSI=1; ordinary test runs skip them. The test process architecture must match Windows. x64 emulation is not ARM64 native acceptance. The script requires every TRX result to execute and pass; zero results or any skipped case cannot produce a successful receipt.
Default evidence is %LOCALAPPDATA%/ShouBuild/generated-uninstall-tests/run-<id>; -ArtifactsRoot selects another local build directory. Runs retain source commit/worktree digests, toolchain details, TRX, generated MSI, installation/teardown logs, stage JSON, file hashes and private records. Successful runs write verification.json. Teardown rechecks ProductCode, PackageCode, name, publisher, location and current-user context before uninstalling only its own matching product. It accepts no arbitrary product code, recursively deletes no unknown residuals and retains generated evidence for review.
Tests await the installer’s actual exit without killing or abandoning it on a test timeout. Forced interruption, process crashes or failed teardown verification can leave the generated product installed. Preserve logs and inspect independently; missing success receipts do not establish that nothing changed. This simple MSI retaining unregistered files does not establish data preservation for other installers. MSIX, interactive installer cancellation, restart, WinUI, other architectures and signing need separate evidence.
The Generated Windows system fixtures GitHub workflow provides a separate manual entry for MSI and inert scheduled-task suites on Server 2025 x64 and Windows 11 ARM64, using the same scripts and requiring native PowerShell/.NET architectures. It retains failure evidence; ordinary push/PR tests install no packages. The MSI script requires six passes, stable source digests, every generated product absent at its final checkpoint and closed public-gate evidence. Its Server x64 and Windows 11 ARM64 generated-suite results establish the native API chains on those respective hosts, without establishing real-product compatibility, ordinary-user complete WinUI or signed installation acceptance.
The five cloud cases on 2026-10-26 failed during discovery before product-uninstall assertions. The tested delta changed installation arguments to ALLUSERS=""; delta five restored the current ALLUSERS=2 MSIINSTALLPERUSER=1 without rerunning the special suite. A clean 58dccc1 Windows Server 2025 x64 run then reproduced all five failures: the unique current-user installation was discovered through the machine registry, with Assignment=0 in the installer log. The correction uses the system API as the context authority and adds assignment-type/directory matching under the application contract; registry location grants no permission. See SYNC.md for actual rerun results. MSI authoring follows Microsoft’s File table, Word Count property and standard action sequence.
startup list [--source <source>] [--search <text>] [--offset <n>] [--limit <n>] [--max-entries <n>] [--max-seconds <n>] --json queries fixed Run/RunOnce keys, two local Startup folders and visible local boot/logon scheduled tasks and current-user packaged startup declarations without opening cleanup storage. The default shared budget is 2,000 entries/five seconds; maximums are 10,000/60. The page searches and pages an immutable snapshot, preserves previous results during refresh and exposes partial coverage. startup_control_available is currently false on every host: GUI and CLI share a closed public execution gate. A matching native Windows process alone does not enable it. Actual packaged-task activation, effective startup/application activity checks and public control acceptance remain separately evidenced. Source names, read limits, states and flow/sequence diagrams are maintained in the startup contract, with transient fields in the data model. Logic/reference checks do not establish native registry, folder, Task Scheduler COM, native package-manifest reads or UI acceptance.
Recognized scheduled-task items may carry scheduled_task.enabled and task-engine state, independently of effective startup enablement and application activity. Status failures/changes retain the registration with explicit partial coverage. WinUI details show the same observation; no controls or execution rights are added. The startup contract defines property rechecks, state values and remaining native evidence.
shou applications summary --json
shou applications summary --search "Example" --sort registered-size --limit 100 --offset 0 --jsonapplications summary calls Core ApplicationCatalog and WindowsApplicationInventory without constructing the record store. Sources include the current-user shared uninstall key, machine 64/32-bit keys and current-user MSIX. Registered estimates neither measure disk usage nor establish ownership. The application contract owns source scope, budgets, text validation, MSIX filtering and uninstall boundaries.
Optional inputs are --search up to 256 characters, --sort name|registered-size defaulting to name, --limit default 100 within 1–500, and --offset default 0 within 0–20,000. --max-entries defaults to 4,000 with a 20,000 maximum; --max-seconds defaults to ten with a 60-second maximum. Results include observation ID/time, matching total, entries, pagination and source coverage. Any source gap returns partial/exit 6. Each CLI invocation observes again, so pages across calls are not consistent snapshots. An unsupported host returns unsupported_platform before creating storage.
The WinUI applications page searches, sorts and paginates one observation, showing publisher, version, source, estimated size, registration identity and unverified location. Cancellation, refresh and disposal isolate stale results; configuration writes disable navigation. Mac can verify Core, Presentation, CLI and Platform references. Generated native registry fixtures and real MSIX reads require Windows acceptance; this is not uninstall support.
shou applications inspect --application-id <application_id> --json
shou applications plan --application-id <application_id> --review-digest <digest> --allow-installer-data-changes true --json
shou applications plan show --uninstall-plan-id <uninstall_plan_id> --jsonUse the exact application ID from the summary to inspect the installation, then read blocking_reasons, warnings and its fact digest. inspect does not open storage. plan reinspects and saves a fifteen-minute plan only for an unchanged digest without blockers and with explicit installer-data acknowledgement. plan show validates the local record without querying current installation state or granting execution consent. Missing acknowledgement returns installer_data_consent_required/exit 7; changed facts return application_changed/4, unsupported/protected installations return unsupported_capability/8, and invalid saved records return corrupt_record/5.
WinUI offers the same review and initially unchecked acknowledgement, disabling selection changes while preparing. Selection changes and refresh clear old review. MSI binds system ProductCode/PackageCode and context; MSIX binds the current user's exact package identity. System installers can change personal data, and MSIX can remove unused dependencies. Both review and planning freshly inspect installation-directory activity; active or unknown observations block preparation. Core/Platform/CLI and WinUI have current confirmation, system uninstall and outcome-recording source. GUI and CLI share a closed public execution gate; native adapters are independently tested with generated fixtures. Additional residual files and restore remain pending. Reviews and plans report the host's execution_available value. The application contract owns boundaries and diagrams.
WinUI connects separate confirmation, stop-and-wait and record queries. Execution disables other-page navigation; normal closing requests stop and retains the window. Record errors retain the exact-plan query. The window lifecycle contract owns dispatcher handling, recorded versus current state and forced-termination limits. Source and page-state tests do not establish native UI acceptance.
shou applications execution show --uninstall-plan-id <uninstall_plan_id> --json
shou applications uninstall --uninstall-plan-id <uninstall_plan_id> --jsonexecution show only reads existing records and validates plan/actor/state binding. Missing records return not_found/5 without creating storage, observing again or retrying. Public uninstall currently reports unsupported_capability/8 on every host without prompting or invoking an installer. The independently tested native service source includes plan rechecks, current confirmation, exact MSI/MSIX invocation, identity observation and terminal recording; generated fixtures do not open the public entry. application_uninstall_available is discovered independently from ordinary file mutation.
Execution source uses single-use consent issued by the same service instance for at most one minute, with exact phrase UNINSTALL <uninstall_plan_id>. Expiry returns plan_stale/4 or confirmation_required/7; any existing intent returns plan_consumed/4, including unknown or corrupt outcomes. Unconfirmed intent/result publication returns journal_write_failed/5 and requires reading existing records plus independent verification, without automatic replay. Native acceptance must precede enabling this entry, and terminal confirmation/data/process warnings remain required. Installer terminal status and exact identity observations are separate. Completion returns success/0, cancellation cancelled/130, and failure or unknown partial/6. restart_required reports a system fact without initiating restart. The system uninstall contract owns invocation/cancellation, storage failure and independent acceptance boundaries.
The source can use bundled rules without importing a personal rule. These commands still require native Windows acceptance:
shou rules catalog --json
shou system locations --include-projects true --json
shou system scan --include-projects true --max-entries 100000 --max-seconds 120 --jsonWithout a workspace, rules catalog reads bundled templates only and can be checked on Mac; --workspace returns full definitions applicable to that location. The catalog contains 23 fixed Windows locations and 39 applicable templates, including 16 project templates. Both platforms read conventional project directories from project-locations.json. Local/Roaming AppData paths use actual system directories, including redirected locations, rather than assuming they are under home.
system locations only inspects a bounded set of location metadata, without registration or traversal. It defaults to fixed locations; --include-projects true adds registered roots and conventional project directories without recursively searching home. Registered scopes take precedence; suggestions cannot expand or overlap them, and physical identities are deduplicated. Missing automatic locations are skipped; permissions, links, ownership and changed registered-root identities produce issues. Discovery has a ten-second deadline.
system scan reinspects discovered directory identities, then checks the discovery revision and registers the batch in one configuration transaction. Conflicts publish no partial registration. Reused locations retain logical references, exclusions and bindings. Scans then run sequentially with shared entry and traversal/classification time budgets; exhausted locations report gaps, and fair scheduling is not implemented. Results contain independent scans, issues, state and the host's cleanup execution_available; gaps return partial/exit 6. Registration commits before scanning: cancellation does not undo registered locations or earlier published scans.
WinUI Scan All Locations calls ScanRegisteredAsync through the same batch observation orchestration, passing only the exact location IDs listed on the page without discovery or registration. Results aggregate across locations with optional location filters, and stopping preserves earlier saved snapshots. Configuration invalidation or failed plan revalidation clears the reusable batch. Windows scanning and review owns states, selection boundaries and flow/sequence diagrams. Categories, filtering, explicit recommendation selection and multi-location plans have source implementations. One current confirmation and per-item live verification share the execution service; execution gates stay disabled.
Applicable built-ins participate in scans by default. Configuration stores enable/disable preferences by stable rule ID, so disabled preferences survive resource upgrades; definitions always come from the current bundle. Fixed cache locations require exact path mapping; overlapping or ambiguously spelled scopes cannot fall back to generic project templates. Built-in scans still apply source protection, exclusions and coverage checks; tool exceptions remain pending.
sequenceDiagram
actor Caller as User or agent
participant Entry as CLI or cleanup page
participant Locations as Location service
participant FS as Filesystem
participant Config as Configuration service
participant Scan as Scan service
Caller->>Entry: Find locations or system scan
Entry->>Locations: Include project directories or not
Locations->>Config: Read revision and registered scopes
Locations->>FS: Bounded identity checks and deduplication
Locations->>Config: Reinspect identities and register batch
alt Configuration or scope conflict
Config-->>Entry: Refuse registration and require refresh
else Registration succeeds
Config-->>Entry: Actual locations with preserved preferences
opt system scan
Entry->>Scan: Scan locations sequentially under shared budgets
Scan-->>Caller: Independent snapshots and coverage issues
end
end
The CLI source provides workspace registration, exclusions, versioned rule import and enablement, enabled-rule scans, draft previews and paged results. Commands follow the shared CLI contract; native runtime acceptance remains pending:
shou workspaces add --path "C:\Users\Alice\Projects" --root-ref developer-workspaces --json
shou rules validate --file ".\cache.rule.json" --json
shou rules import --file ".\cache.rule.json" --json
shou rules preview --file ".\cache.rule.json" --workspace "<returned-workspace-id>" --json
shou scan results --scan-id "<returned-scan-id>" --limit 50 --json
shou rules enable --rule-id "<imported-rule-id>" --workspace "<returned-workspace-id>" --json
shou scan --workspace "<returned-workspace-id>" --jsonImport does not enable a rule. rules enable changes a local binding without authorizing cleanup. rules show and rules export return a shareable definition in the result envelope; Windows rules export currently has no --output. rules list returns personal versions and bindings and reports builtin_templates_available=true for the separately queryable catalog.
analysis scan returns bounded in-memory measurements without saving records. rules preview evaluates one draft independently and saves preview_only=true evidence; after enablement, use scan --workspace to scan again. A regular scan freezes current effective built-in definitions and explicitly enabled personal versions, returning preview_only=false; without applicable rules it only measures. Both summaries return rule IDs and digests in a rules array. Directed cleanup observations return scope=rule_targets and tree_complete=false; state=complete covers this rule discovery and target measurement, independently of whole-tree space analysis. Planning and preflight recheck selected targets and project context under the scan budget and completeness contract. scan results preserves the source marker, and cursors bind the scan ID, saved bytes and offset, with page sizes from 1–500.
Candidates are review or blocked. The CLI reports cleanup execution_available for the current host. plan create assembles a plan without changing targets; public plan execute currently returns unsupported_capability/8. Separate native generated fixtures verify explicitly confirmed permanent actions without opening the public gate. Source, credentials, databases, unknown links and unclassified data remain conservatively protected. Personal rules cannot request built-in tool exceptions.
Each directory gets positive completeness evidence only after traversal and reinspection. Unrelated gaps preserve independently complete candidates; incomplete targets remain blocked. Global, workspace and rule exclusions combine, and protected descendants block their whole parent target. Retention uses the newest descendant modification time, never access time as proof of inactivity.
Scanning defaults to 100,000 entries, 120 seconds and 32 levels, with maxima of 1,000,000 entries, 3,600 seconds and 64 levels. All rules share a 2,000,000-operation classification cap and the remaining scan time. Snapshot serialization and publication occur outside that traversal time budget, with a 128 MiB limit. Cancellation publishes no snapshot; partial coverage and classification limits remain visible. A configuration change during scanning returns plan_stale and prevents publication as current evidence.
sequenceDiagram
actor Caller as User or agent
participant CLI
participant Scan as Scan service
participant FS as Filesystem
participant Store as Record store
Caller->>CLI: scan or rules preview with explicit workspace
CLI->>Scan: Entry kind, optional draft and budget
Scan->>Store: Read configuration, enabled versions, root identity and revision
Scan->>FS: Bounded read-only scan and directory completion checks
FS-->>Scan: Entries, complete subtrees and coverage gaps
Scan->>Scan: Share observed tree and budget, match, exclude and protect
Scan->>Store: Acquire lease and re-read configuration
alt Configuration digest remains unchanged
Scan->>Store: Atomically publish scan with preview_only marker
Scan-->>CLI: Scan ID, exact rules, coverage and candidate count
CLI-->>Caller: Review result and paged query entry
else Configuration changed
Scan-->>CLI: plan_stale
CLI-->>Caller: Review and scan again
end
WinUI's Cleanup Rules page uses the same configuration service as the CLI. Users can prepare personal-rule scans without a terminal:
- Import a JSON rule through the system file picker, using the CLI's native file-reading adapter with a 256 KiB limit and ten-second deadline. It refuses links and checks identity and metadata before and after reading. Core validates the closed schema and immutable version. Import does not change the enabled version; rules for other platforms are visible but cannot be enabled on Windows.
- Select an exact rule version. Its existing matching scan location is selected automatically. Otherwise, Choose Folder for This Rule registers a selected directory using the rule's logical reference; Core/Platform verifies the real path and current-user identity. Each logical reference binds one directory and is never silently rebound.
- Enable that version at the selected location. Importing a newer version preserves the previous binding; the page shows the actual bound version. Disable acts only on the explicitly selected version when it is currently enabled.
- Return to cleanup and run a fresh scan before reviewing candidates. Built-ins follow the selected location and can enable/disable the currently bundled version; personal rules retain exact immutable version bindings. Recommendations include only complete, unblocked review-risk candidates under complete batch coverage; high-risk items still require explicit selection.
A scan location can be removed after a dialog shows its exact path and explains that target files and imported rules remain. Its bindings and local exclusions are removed from configuration. Exclusion settings support all locations, the selected location and a project. Preview the resolved relative pattern before saving; a blank project pattern protects the entire project (**), and the project directory must be an exact relative path. Inherited global protections are shown separately and can only be removed in the all-locations scope. Rule-owned exclusions remain in the rule definition.
ConfigurationViewModel serializes page reads and writes. Conflicting actions and page changes stay disabled until both the write and persisted-state reload finish. Starting a refresh or save immediately invalidates cleanup scope, scans, selections and plans; late results cannot restore old evidence. Dispatched configuration writes offer no cancellation or rollback guarantee: closing the window suppresses page notifications and does not mean the write was undone. While the process remains alive, success, failure and cancelled responses all trigger a reload of actual configuration. A failed reload clears editable state and requires refresh. Cancelling a file/folder picker or exclusion preview does not dispatch a write.
flowchart TD
Discover[Find scan locations] --> Builtin[Select location and review built-in preferences]
Builtin --> Scan[Run a fresh scan]
Import[Import personal rule] --> Version[Select exact version]
Version --> Location{Matching scan location exists?}
Location -->|Yes| Reuse[Use existing location and binding]
Location -->|No| Choose[User chooses and registers folder]
Reuse --> Enable[Explicitly enable selected version]
Choose --> Enable
Enable --> Scan
Protection[Preview and save exclusion] --> Scan
Scan --> Review[Select complete unblocked targets and review]
sequenceDiagram
actor User
participant UI as Configuration page
participant VM as Configuration state
participant Review as Cleanup state
participant Core as Configuration service
User->>UI: Confirm exact configuration change
UI->>VM: Save exact version, location or exclusion
VM->>Review: Cancel old reads and clear scans and plans
VM->>UI: Disable conflicting actions
VM->>Core: Validate and persist under lease
Core-->>VM: Write response or exception
VM->>Core: Reload regardless of write response
alt Configuration verifies
Core-->>VM: Actual versions, bindings and exclusions
VM-->>UI: Show actual state and any save error
else Reload fails
Core-->>VM: Error
VM-->>UI: Clear editable state and require refresh
end
WinUI source provides storage analysis, cleanup review, cleanup rules and history navigation. Find Scan Locations prepares fixed and conventional project directories; users then select one location to scan built-ins and enabled personal rules. Preparation clears old evidence immediately and reloads actual configuration after success or failure. Dispatched registration offers no stop or rollback guarantee; closing the page only suppresses late results. The configuration page refreshes to show built-in preferences. The GUI can scan all configured locations listed on the page and review aggregated categories, rules and paths, retain selections across location filters, explicitly select recommendations and review one multi-location plan. Public execution and native acceptance remain pending.
CleanupReviewViewModel owns asynchronous state, explicit selection and plan review. App's NativeReviewOperations composes Core/Platform and moves service work off the UI thread. The page displays 200 candidates at a time and retains at most 256 manual selections across pages. High-risk items start unselected. Blocked, incomplete, draft, duplicate-scope and overlapping parent/child targets cannot enter the review selection. The page explains blocking reasons while domain services retain final eligibility and fresh validation.
Smart Cleanup and Developer Projects use one window-owned CleanupReviewViewModel; switching pages does not reload, rescan or clear selection. Each scope retains its category, rule and search filters. Core CleanupReviewProjection groups existing evidence by the nearest regular project marker, labels scan-location fallbacks and deduplicates cross-root/parent-child candidates before totaling bytes. Built-in project caches also enter the project scope; personal rules need a marker and a scan root disjoint from fixed shared caches. Rows expose full paths, tri-state selection, matched bytes and pagination scope. Group selection affects all current filter matches; the footer and plan include only selected project sources. Project recommendation/clear actions preserve other selected caches; both pages share the atomic 256-item limit. Switching scope invalidates plans and cancels/rejects late planning results without granting new execution eligibility.
Changing a single-scan location clears its old selection and plan. Filtering batch observations by location retains selections from other locations. Refresh or configuration changes invalidate all old evidence. New requests isolate late responses, and failed planning requires a fresh scan. Cancelled single-location scans and planning requests do not publish unacknowledged results; batch reads retain previously published snapshots, and mutation attempts retain actual recorded outcomes. Configuration writes follow the persisted-state reconciliation above.
Review Selected Items explicitly creates a permanent-action plan and only displays full paths, count, estimated size and risk; it never issues consent. Clean Permanently has separate confirmation and execution source; it stays disabled by the shared native-acceptance gate. Review source and presentation tests do not establish native mutation acceptance.
History queries 50 recorded summaries per page, with details re-reading and validating the plan. Check Recorded Locations only observes exact locations. Recorded results and current observations are displayed separately; unknown or unfinished intent never becomes success because an original path disappeared. Paging and refresh do not merge different query snapshots, and changing records clears old observations. There are no recovery, retry or journal-write controls.
sequenceDiagram
actor User
participant UI as WinUI pages
participant VM as Presentation
participant Core as Core services
participant Native as Windows adapters
User->>UI: Choose a configured location and scan
UI->>VM: Clear old scope and selection, start cancellable scan
VM->>Core: Use current enabled rules
Core->>Native: Bounded reads and saved scan evidence
Native-->>Core: Identities, coverage and gaps
Core-->>VM: Candidates and blocking reasons
VM-->>UI: Paged results, all initially unselected
User->>UI: Select and review exact targets
UI->>VM: Explicit candidate IDs
VM->>Core: Create permanent-action plan
Core->>Native: Recheck identity, full manifests and activity
Core-->>VM: Immutable plan or blocking reason
VM-->>UI: Full scope, execution stays disabled
User->>UI: Open history and check recorded locations
UI->>VM: Exact execution and inspection request
VM->>Core: Read-only details and observations
Core-->>VM: Recorded facts and current observations
VM-->>UI: Separate facts without upgrading unfinished intent
CleanupExecutionViewModel is separate from review state and binds only the current permanent-action plan. App checks WindowsCleanupMutation.PublicExecutionAvailable, then uses the same Core service for current confirmation and single-use consent consumption. GUI and CLI read that one disabled gate, with no environment override. WinUICleanupConfirmation displays exact plan paths, count, risk and irreversible consequences on the UI thread, defaults to Cancel and rejects a cancelled or no-longer-visible review.
Dispatch clears executable plans, scans and selection; changing scope or leaving the cleanup page is blocked until the task returns. Stop and normal window closing request cooperative cancellation and keep the window waiting. Returned recorded outcomes remain visible even after stop. Forced process termination is outside that guarantee. Existing intent, unknown outcomes and journal failures are never automatically retried. The page retains exact-plan record lookup; absence of a readable record does not prove no mutation. Lookup validates that plan's journal without rewriting state or granting recovery.
flowchart TD
Plan[Current explicitly selected permanent plan] --> Gate{Shared native-acceptance gate open?}
Gate -->|No| Unavailable[Unavailable without confirmation or execution]
Gate -->|Yes| Confirm[Separate native confirmation defaults to Cancel]
Confirm -->|Not confirmed| Stop[Retain lookup without executing]
Confirm -->|Confirmed| Execute[Clear executable state, Core rechecks and journals intent]
Execute --> Wait[Retain page and window during execution]
Wait -->|Stop or normal close| Cancel[Request cooperative stop and keep waiting]
Cancel --> Result[Show actual recorded item results]
Wait -->|Task returns| Result
Result --> Lookup[Read exact-plan records when needed]
sequenceDiagram
actor User
participant UI as Cleanup page and state
participant Core as Cleanup service
participant Store as Private record lease
participant Native as Windows adapters
Note over UI,Native: Gate is disabled, this execution source still requires native acceptance
User->>UI: Execute current plan and separately confirm exact scope
UI->>Core: Current plan and confirmation interface
Core->>UI: UI-thread confirmation defaults to Cancel
UI-->>Core: Explicit consent for this call
Core->>Store: Acquire lease, revalidate plan and journal item intent
Core->>Native: Recheck identity and complete manifest before mutation
User->>UI: Stop or normally close window
UI->>Core: Request cooperative stop and retain page/window
Native-->>Core: Actual current-item outcome or unknown
Core->>Store: Save observed result and stop further dispatch
Core-->>UI: Recorded final state or structured error
UI-->>User: Itemized outcomes and read-only lookup
Core implements planning, current confirmation and item journal orchestration, verified with in-memory fixtures. The CLI assembles native filesystem, activity and mutation adapters. plan create and plan show create and read plans; public plan execute currently returns unsupported_capability (exit 8) on every host before touching targets. Generated fixtures independently exercise confirmed native actions and item records without opening that gate. Discovery exposes the runtime gate; there is no environment-variable override. Native fixture and interactive UI evidence remain separate acceptance gates. WinUI includes separate confirmation, stop-and-wait, recorded-result lookup and normal-close protection source.
shou plan create --scan-id "<regular-scan-id>" --candidate "<candidate-id>" --mode permanent --json
shou plan show --plan-id "<returned-plan-id>" --jsonFollowing the shared contract, CLI --mode defaults to trash. Trash is currently unavailable, so the default action returns unavailable; creating a permanent plan requires explicit --mode permanent, without fallback. Creating a plan never deletes files. Repeat --candidate for multiple selections; implicit select-all and duplicate IDs are refused.
Only regular enabled-rule scans can produce plans, with 1–256 explicitly selected, complete, non-overlapping targets. Plans freeze configuration, rules, manifests, ancestor identities and marker metadata, action and a ten-minute lifetime, then freshly observe the filesystem. Activity must be known idle; unknown activity blocks planning and execution.
Current confirmation binds the service instance, plan digest and action, lasts at most one minute, is consumed once and cannot be restored from JSON. Terminal confirmation source displays full scope, digest, risk and the irreversible-action warning on stderr, requiring exact PURGE <plan-id> or TRASH <plan-id> input. Input is limited to 256 characters within one minute; stdin and stderr must be interactive terminals, while stdout may carry JSON. Control characters in paths and rule fields are escaped. Injected-prompt logic tests have run; actual Windows Console behavior remains unaccepted, and the disabled execution entry never prompts.
Prompts do not hold the mutation lock. Execution holds an asynchronous storage lease, validates the frozen plan scope and freshly verifies each item, persists purging or moving before calling the native port, then saves the observed result. Unknown outcomes stop dispatch; journal failures return journal_write_failed. Any existing execution intent prevents plan replay, and missing final state never proves success. Recovery remains pending; read-only history entries are described below.
flowchart TD
Select[Explicit candidate IDs and action from a regular scan] --> Create[plan create: recheck configuration, manifests and activity]
Create --> Valid{Complete current evidence and known idle?}
Valid -->|No| Reject[Return blocking reason without changing targets]
Valid -->|Yes| Save[Save immutable plan valid for ten minutes]
Save --> Show[plan show: review full scope and digest]
Show --> Execute[plan execute]
Execute --> Disabled[Currently unsupported_capability, exit 8]
WindowsCleanupMutation implements permanent removal only. It pins workspace ancestors and context, opens objects relative to verified parent handles through NtCreateFile without following reparse points, enumerates directories through handles and preflights the full manifest. It then processes selected entries in postorder, unlinking each opened name through POSIX disposition. It never recursively deletes by path or overrides readonly attributes, and requires an image-section check. New objects never enter the manifest; directories must be empty to remove. Only confirmed unlinks count as removed, and unconfirmed outcomes remain unknown. Each item has a cooperative two-minute budget; kernel calls can still block. Cancellation waits for the current native boundary before journaling. Trash currently returns unavailable.
WindowsCleanupActivity combines two read-only observations: Restart Manager file use for target files and parent markers, and a fixed tool-process inventory whose verified working directories are checked for overlap with the target's parent project directory. Core owns the tool-name list; rules cannot supply process names. Shou's current process and processes confirmed exited through opened handles are ignored. No command lines or environments are read, and no elevation or process termination is attempted.
Both checks share a ten-second deadline and bounded native workers. The inventory permits at most 16,384 snapshot rows and 64 matching-tool directory reads. Access failures, unknown directory identities, incomplete snapshots, excess work and timeouts cannot become idle. Positive activity takes precedence; otherwise any unknown blocks, and both observations must be idle to continue. Tools in other projects do not block globally merely by sharing a name.
A directory positively verified outside the project/ancestor scope does not need the target owner's SID; it grants no cleanup authority. Missing directory evidence still blocks, and overlapping foreign-owner scopes remain unknown. Target, context and workspace ownership checks are unchanged.
The directory adapter uses NtQueryInformationProcess and ReadProcessMemory to read PEB directory fields, rechecking pointers, directory bytes and filesystem identity before and after, with native 64-bit and WOW64 layouts. This internal ABI has no Windows runtime evidence yet. Working directories are activity clues: tools accessing a project through absolute arguments from unrelated directories may escape observation. This does not detect every use. Public mutation stays disabled pending native process, race, interruption and terminal acceptance.
sequenceDiagram
participant Cleanup as Cleanup domain service
participant Activity as Activity checks
participant Files as Restart Manager
participant Processes as Tool-process observation
Cleanup->>Activity: Exact target manifest and project context
par Shared ten-second deadline
Activity->>Files: Inspect exact files and markers
Files-->>Activity: Active, idle or unknown
and Bounded process inventory
Activity->>Processes: Fixed names and verified working directories
Processes-->>Activity: Project overlap, no overlap or evidence gap
end
Activity-->>Cleanup: Active first, otherwise unknown blocks, both idle to continue
flowchart TD
Intent[Core persisted item intent] --> Pin[Pin workspace, ancestors and marker handles]
Pin --> Preflight[Open relative to handles and preflight frozen manifest]
Preflight --> Entry[Next selected descendant, directories last]
Entry --> Check{Identity and context match, directory empty?}
Check -->|No| Partial[Return confirmed count and failure reason]
Check -->|Yes| Unlink[Set disposition on verified handle and close]
Unlink --> Verify{Original name no longer references original object?}
Verify -->|Unconfirmed| Unknown[Return unknown and stop dispatch]
Verify -->|Yes| More{More entries and not cancelled?}
More -->|Yes| Entry
More -->|No| Result[Return observed completion or cancellation]
Result --> Journal[Core saves item result]
Partial --> Journal
Unknown --> Journal
The CLI includes the following read-only commands, with native runtime acceptance pending. Public cleanup is unavailable, so these queries do not create new user cleanup records.
shou plan show --plan-id "<saved-plan-id>" --json
shou history list --limit 50 --json
shou history show --execution-id "<saved-execution-id>" --json
shou history inspect --execution-id "<saved-execution-id>" --max-entries 100000 --max-seconds 120 --jsonhistory list reads journal summaries under one storage lease without loading target manifests and reports plan_verified=false. Pages default to 50 rows, at most 500, sorted by descending start time then ascending execution ID. Each query is bounded by 4,096 total private-directory entries, 32 MiB of execution bytes and ten seconds; exceeding a budget returns resource_limit or time_limit. Cursors bind the journal set, raw-byte digests, page size and offset; changed records return source_changed. Corrupt rows appear in issues while readable rows remain accessible. No continuation is returned when raw bytes cannot be read. Gaps return status=partial and exit 6.
history show re-reads the corresponding plan and validates digest, action, timestamps, item IDs, state combinations and receipt identities. plan show only reads and validates the plan. Expired history remains readable and never restores confirmation authority. Historical queries do not require the current configuration to retain the workspace or rule.
history inspect holds the same cross-process lease from record opening through observation. It only checks exact original paths and recorded Trash locations, never searches the recycle bin, rewrites journals or retries operations. --max-entries and --max-seconds use the scan limits and apply jointly across every target and location. Entry accounting includes root-location observations and entries returned by scanning; directory depth is capped at 64.
The report preserves recorded_state, unfinished and checked_at. Locations are matches, missing, changed, unavailable or not_recorded. A match requires the complete manifest, identities and metadata; Windows does not relax Trash-root change timestamps. Each item's assessment is verified_permanent, verified_trash, unchanged, conflict or needs_verification. Only recorded permanent completion plus a missing original can report verified_permanent; purging or unknown remains uncertain even when the original disappears. Unfinished executions remain unfinished. Budget gaps, uncertainty or conflicts return status=partial and exit 6; caller cancellation returns 130. Every result reports records_changed=false and recovery_available=false.
sequenceDiagram
actor Caller as User or agent
participant History as History service
participant Store as Record store
participant FS as Filesystem
Caller->>History: inspect with execution ID and shared budget
History->>Store: Acquire read lease without creating missing data root
Store-->>History: Execution journal and immutable plan
History->>History: Validate digest, identities and state bindings
loop Each recorded original and Trash location
History->>FS: Bounded identity and complete-manifest observation
FS-->>History: Match, missing, changed or evidence gap
end
History->>History: Preserve journal state and assess observations
History->>Store: Release lease without writing records
History-->>Caller: Observations, verification needs and unavailable recovery
The default data root is %LOCALAPPDATA%/Shou/Data. SHOU_DATA_DIR can select an absolute local directory whose parent already exists and belongs to the current user. Read-only queries against missing storage do not create the data root. Directories and files use restricted ACLs for the current user and SYSTEM. Existing broad permissions, junctions, cloud placeholders and multi-link records are refused without changing permissions.
Reads and updates share a cross-process lease; contention returns store_busy. Updates write and flush a unique temporary file, then publish through pinned directory and file handles. Atomic replacement of one record is not a multi-record transaction. A flush failure after publication returns commit_unconfirmed: callers must inspect the outcome before retrying. See the Windows data contract for formats and limits.
These source commands are separate from startup discovery. Review opens no storage; execution and record lookup use current-user private operation records.
shou startup inspect --task-path '\Folder\Task' --action enable --json
shou startup control --task-path '\Folder\Task' --action enable --review-digest sha256:<digest> --json
shou startup execution show --startup-operation-id startup_control_<id> --jsonActions are only enable|disable. inspect returns a five-minute in-memory review, blocking reasons and the host's execution_available. Public control currently returns unsupported_capability / 8 on every host without prompting or setting the task. The independently tested native service rechecks the original digest, requests current confirmation (STARTUP ENABLE <current-operation-id> or STARTUP DISABLE <current-operation-id> for the TTY adapter) and changes only the scheduled-task Enabled flag; generated fixtures do not enable the public entry. No --yes, --approved or retry flags are accepted.
execution show is read-only; absent records return not_found / 5 without creating storage. Changed tasks return startup_changed / 4. Journal failure returns partial / 6 with the operation ID and a lookup next_action; missing output does not prove no change. Unsupported hosts return 8 without creating a data directory. The startup contract owns eligibility, safety and UI waiting behavior; the data model owns storage. Native control and UI acceptance remain pending.
Status: a separate entry and six native cases have source implementations. Mac checks establish compilation, explicit skipping and script refusal only; Windows execution remains unverified. The entry directly exercises the native adapter and Core service with the public product gate still disabled. It does not accept WinUI or real terminal confirmation.
On matching native Windows 11 x64 / ARM64, use PowerShell 7.4 or newer, the pinned .NET SDK and Python from the repository root:
& "./scripts/windows/test-startup-fixtures.ps1" -RunGeneratedStartupFixturesOptional -ArtifactsRoot selects output on a fixed local drive, defaulting to %LOCALAPPDATA%/ShouBuild/generated-startup-tests. Shared/mapped-network drives and UNC paths are unsupported. No existing task, executable or account parameters are accepted, and no elevation is requested. Missing opt-in, unsupported host/architecture and unknown task parameters are rejected. Default test runs skip these six task-mutation cases.
Each case creates one current-user task beneath a random \ShouGeneratedStartup-<id> folder. The task starts disabled, its sole current-user logon trigger and demand starts are explicitly disabled, and its action points to a nonexistent fixture-local .exe. No API to run tasks is called. Registration is create-only; the definition-change case is update-only so an update cannot create a missing task.
| Case | Native behavior under test |
|---|---|
| Switch round trip and lookup | Enable/disable setters, rereads, durable outcomes, reopened lookup, replay rejection and no arguments in journals |
| Declined current confirmation | Unchanged switch, no mutation invocation or durable intent |
| Definition changes during confirmation | Change only the generated task's Hidden setting, reject changed digest without intent |
| Stop during confirmation | Correct approval cannot override cancellation; no intent |
| Actor mismatch at the native boundary | Reject another actor without changing the switch |
| Stop after intent but before dispatch | Persist cancelled/not_started, preserve the switch and prevent intent replay |
Teardown rechecks the current actor, exact folder/task, owner, unique generated marker, disabled trigger/demand starts and definition digest. It removes only that task and the verified-empty generated scheduler folder. It never recursively deletes a filesystem tree. Unverified ownership or definition refuses teardown and retains diagnostics. Generated marker files, stage JSON and private operation records remain in the output directory.
The script requires all six cases to execute and pass; skips are failures for acceptance. It compares before/after source digests and checks all six initial-disabled and final-folder-removal receipts. Output includes TRX, toolchain, system/process architectures, source state, stage facts, operation records and a verification.json with file SHA-256 hashes. Ordinary discovery never opens these records. This entry does not cover forced interruption during a call, concurrent replacement/ABA, permission matrices, real terminals, WinUI, other startup sources or signed distribution; it cannot by itself enable the product gate.
privacy scan [--range last-hour|last-day|last-seven-days|all-time] saves fixed-window aggregate observations. privacy scan show --scan-id <privacy_scan_id> strictly reads metadata without querying browser records again. The WinUI Privacy page explicitly starts the same Core service through PrivacyScanViewModel; range/configuration changes clear results, Stop discards late results, and navigating away cancels scanning. No source is automatically scanned on navigation and no privacy deletion action is exposed. Partial observations return CLI status partial, exit 6.
Source, ACL/handle, SQLite, budget and unsupported-schema contracts belong to privacy cleaning; platform-specific records belong to the data model. Plans, confirmation, transactional deletion and receipts remain to be implemented.