> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase38-session03-aggregate-and-dream-health/spec.md). # Session Specification **Session ID**: `phase38-session03-aggregate-and-dream-health` **Phase**: 38 - Claude OS v2.8.1 Semantic Port **Status**: Not Started **Created**: 2026-06-29 *** ## 1. Session Overview This session ports the Phase 38 Tier 1.2 aggregate work into AI OS's modular script architecture. Sessions 01 and 02 are complete, so the shared platform helper now exists and can be used by aggregate, scanner, detection, and sanitizer modules without copying upstream's monolithic `scripts/aggregate.ts`. The session delivers two linked outcomes: Windows-aware aggregate behavior and browser-safe Dream health metadata. Aggregate output must degrade cleanly when Windows registries, app locations, Obsidian config, or directories are missing, and `src/data/live-data.json` must expose `dream.healthStatus` and `dream.fixHint` for the later dashboard Dream product work. The non-negotiable delivery bar is a real aggregate run. Tests must cover the branch behavior, but the session is not done until `bun run aggregate` or the equivalent host-local aggregate path writes inspectable live data with the new Dream health fields and no private path or credential leakage. *** ## 2. Objectives 1. Adapt Windows app, terminal, path, Obsidian, and redaction behavior into existing AI OS aggregate modules. 2. Add Dream health mapping for `healthy`, `never_ran`, `stale`, and `silent_failure` from AI OS Dream observability and output state. 3. Preserve macOS/Linux aggregate behavior while adding graceful degradation for missing registries, unreadable directories, and unavailable Windows app locations. 4. Prove the behavior with focused tests, privacy-safe aggregate-output checks, and one real aggregate write to `src/data/live-data.json`. *** ## 3. Prerequisites ### Required Sessions * [x] `phase38-session01-tier-0-parity-fixes` - Provides the Tier 0 Phase 38 baseline. * [x] `phase38-session02-platform-foundation` - Provides `scripts/lib/platform.ts` helpers for path normalization, app-data paths, CLI candidates, and venv paths. ### Required Tools Or Knowledge * Bun 1.3.14, Vitest, and existing script test commands. * Existing aggregate modules under `scripts/lib/`. * Dream runtime contracts under `scripts/lib/dream/`. * Upstream comparison paths under `/home/aiwithapex/projects/claudeos/`. ### Environment Requirements * Repository root is `/home/aiwithapex/projects/aios`. * Windows-specific behavior can be proven with injected platform/env/filesystem harnesses when a native Windows host is unavailable. * A real aggregate write must be run locally against AI OS output paths before validation. *** ## 4. Scope ### In Scope (MVP) * Operators running aggregate on Windows get useful app and terminal detection - adapt Start Menu, `%LOCALAPPDATA%\Programs`, Program Files, CLI, and terminal inference into `scripts/lib/app-detection.ts` and `scripts/lib/tool-detection.ts`. * Aggregate path handling avoids duplicate or inflated counts from backslash and drive-letter variants - normalize path labels in scanner helpers and session/skill scanner owners. * Obsidian vault discovery finds supported Windows registry/config sources and treats missing or unreadable registry/config data as degraded metadata, not aggregate failure. * Browser-safe live data includes `dream.healthStatus` and `dream.fixHint` - map these from AI OS Dream output, lifecycle, material readiness, and observability records. * Redaction covers Windows usernames, home paths, emails, configured redaction names, and private path variants before generated data is written. * Tests cover Windows branch behavior, Dream health mapping, redaction, Obsidian fallback, aggregate-output privacy, and macOS/Linux regression baselines. ### Out Of Scope (Deferred) * New Dream execution runners - Reason: AI OS Dream execution is already owned by `scripts/lib/dream/**`, `scripts/dashboard-dream-run.ts`, and `scripts/scheduler-runner.ts`. * Windows Task Scheduler install mechanics - Reason: owned by Session 04. * Setup Dream engine selector - Reason: owned by Session 07. * Dashboard Dream engine UI or health-aware cards - Reason: owned by Session 07 after these live-data fields exist. * Request-time bridge CLI resolution and Host-header hardening - Reason: owned by Session 05. *** ## 5. Technical Approach ### Architecture Use `scripts/lib/platform.ts` as the shared base for path normalization, app-data roots, CLI candidate directories, executable names, and Windows branch injection. Do not recreate upstream's flat aggregate logic. Instead, route each upstream concern to the AI OS owner already named by the Phase 38 stub: app and terminal detection in `app-detection.ts`, CLI behavior in `tool-detection.ts`, path label handling in scan/session/skill helpers, Obsidian discovery in `memory-scanner.ts`, redaction in `sanitize.ts`, Dream health mapping in a focused Dream helper, and live-data assembly in `aggregate-orchestration.ts`. Add a small Dream health mapper under `scripts/lib/dream/health.ts` that accepts the latest Dream output/load result, runtime lifecycle summaries, material readiness, and current aggregate timestamp, then returns a bounded browser-safe status and fix hint. The aggregate should attach this metadata to the existing Dream object when output exists and emit a minimal metadata object when no Dream has ever run, so `dream.healthStatus` is always visible after a real aggregate. Keep aggregate write validation and privacy gates as the final boundary. The generated data must pass existing `prepareLiveDataForWrite()` privacy checks, and tests should prove that Windows paths and usernames are redacted before write. ### Design Patterns * Module-owner adaptation: Port concepts into the AI OS modules that already own the behavior. * Injectable platform/filesystem harnesses: Test Windows branches without mutating process globals or requiring a native Windows host. * Additive live-data contract: Add typed Dream health fields while preserving compatibility with older Dream payloads. * Degraded-not-failed scanners: Missing registries, missing app folders, and unreadable directories become bounded warnings or empty detections. * Privacy at write boundary: Redact before emission and keep generated live data free of private paths, emails, tokens, and raw logs. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------- | | `scripts/lib/dream/health.ts` | Map AI OS Dream output, lifecycle, and material readiness into browser-safe `healthStatus` and `fixHint`. | \~140 | | `scripts/lib/__tests__/dream-health.test.ts` | Cover `healthy`, `never_ran`, `stale`, and `silent_failure` mapping plus sanitized hints. | \~180 | ### Files To Modify | File | Changes | Est. Lines | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------- | | `scripts/lib/app-detection.ts` | Add Windows-aware app and terminal detection using platform helpers with graceful missing-path handling. | \~150 | | `scripts/lib/tool-detection.ts` | Ensure CLI probing consumes the shared Windows candidate directories and executable names needed by aggregate detection. | \~30 | | `scripts/lib/scan-helpers.ts` | Reuse `toPosix`/path helpers where aggregate path labels need platform normalization. | \~30 | | `scripts/lib/session-scanner.ts` | Normalize project/session path labels so backslash paths do not inflate aggregate counts. | \~35 | | `scripts/lib/skill-scanner.ts` | Normalize scanned skill paths and labels consistently with session scanning. | \~25 | | `scripts/lib/memory-scanner.ts` | Add Windows Obsidian registry/config discovery and degraded fallback behavior for missing or unreadable sources. | \~100 | | `scripts/lib/sanitize.ts` | Add Windows username, full-name, drive/home, and path-label redaction coverage. | \~80 | | `scripts/lib/aggregate-orchestration.ts` | Attach Dream health metadata and aggregate warnings while preserving host-local/full aggregate behavior. | \~70 | | `src/lib/live-data-types.ts` | Type the additive Dream health fields. | \~20 | | `src/lib/validate-live-data.ts` | Validate Dream health statuses and bounded fix hints without rejecting old Dream payloads. | \~35 | | `scripts/lib/__tests__/app-detection.test.ts` | Add Windows app, terminal, Start Menu, and missing-location tests. | \~140 | | `scripts/lib/__tests__/tool-detection.test.ts` | Add aggregate-relevant Windows CLI candidate regression tests if not already covered. | \~50 | | `scripts/lib/__tests__/session-scanner.test.ts` | Add backslash/drive-letter path normalization regression coverage. | \~60 | | `scripts/lib/__tests__/skill-scanner.test.ts` | Add path-label normalization regression coverage. | \~45 | | `scripts/lib/__tests__/memory-scanner.test.ts` | Add Obsidian registry/config discovery and unreadable fallback tests. | \~100 | | `scripts/lib/__tests__/sanitize.test.ts` | Add Windows home, username, full-name, and email redaction tests. | \~80 | | `scripts/lib/__tests__/aggregate-orchestration.test.ts` | Add aggregate Dream health assembly and degraded-warning coverage. | \~90 | | `scripts/lib/__tests__/aggregate-live-data-write.test.ts` | Add privacy/write-boundary regression coverage for Windows private paths. | \~50 | | `src/lib/__tests__/nested-validation.test.ts` | Add Dream health validation pass-through and invalid-value normalization tests. | \~45 | | `.spec_system/specs/phase38-session03-aggregate-and-dream-health/implementation-notes.md` | Record implementation evidence during the next command. | \~220 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Windows-aware aggregate detection covers Start Menu `.lnk`, `%LOCALAPPDATA%\Programs`, Program Files, CLI fallbacks, and terminal inference without failing when locations are unavailable. * [ ] Obsidian discovery includes Windows registry/config candidates and degrades gracefully when registry/config data is missing or unreadable. * [ ] Backslash and drive-letter path variants are normalized so session, skill, and memory counts remain stable. * [ ] `src/data/live-data.json` includes `dream.healthStatus` and `dream.fixHint` after a real aggregate run. * [ ] Dream health maps `healthy`, `never_ran`, `stale`, and `silent_failure` from AI OS Dream observability, output freshness, and material readiness. * [ ] Generated aggregate output redacts Windows and POSIX private paths, usernames, configured names, emails, and token-shaped strings. ### Testing Requirements * [ ] Unit tests written and passing for Windows app/tool detection, path normalization, Obsidian fallback, redaction, Dream health mapping, live-data validation, and aggregate assembly. * [ ] Targeted tests run with `bun run test -- scripts/lib/__tests__/app-detection.test.ts scripts/lib/__tests__/tool-detection.test.ts scripts/lib/__tests__/session-scanner.test.ts scripts/lib/__tests__/skill-scanner.test.ts scripts/lib/__tests__/memory-scanner.test.ts scripts/lib/__tests__/sanitize.test.ts scripts/lib/__tests__/dream-health.test.ts scripts/lib/__tests__/aggregate-orchestration.test.ts scripts/lib/__tests__/aggregate-live-data-write.test.ts src/lib/__tests__/nested-validation.test.ts`. * [ ] Script typecheck run with `bun run typecheck:scripts`. * [ ] App typecheck or equivalent live-data typecheck run with `bun run typecheck`. * [ ] Real aggregate run writes inspectable `src/data/live-data.json` with Dream health metadata. ### Non-Functional Requirements * [ ] Missing Windows registries, unreadable directories, and absent app locations are degraded states, not aggregate crashes. * [ ] No new dependencies or lockfile changes are introduced. * [ ] Aggregate warnings are bounded and browser-safe. * [ ] MacOS/Linux aggregate behavior remains compatible with current baseline. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] No product-facing UI copy or debug surface changes. *** ## 8. Implementation Notes ### Working Assumptions * Faithful Windows harness tests are acceptable for implementation before native Windows verification: the Phase 38 PRD allows target-platform proof through Windows or a faithful harness, Session 02 already built injectable platform helpers, and this session's required behavior is mostly filesystem/path/env branch logic that can be tested deterministically. * A minimal Dream object is acceptable when no Dream has ever run: the current aggregate emits `dream: null`, but Session 03 requires `dream.healthStatus` and `dream.fixHint` to be live-data visible; emitting a bounded object with empty prescriptions and `never_ran` status preserves browser-safe visibility without inventing Dream prescriptions. ### Conflict Resolutions * Upstream monolithic aggregate hunk versus AI OS module ownership: the Phase 38 PRD says this is a semantic port and names AI OS target modules; this plan chooses module-owner changes instead of replacing `scripts/aggregate.ts`. * Existing loose Dream validation versus new typed fields: `DreamEntry` currently allows extra keys, while Session 03 requires specific health fields; this plan adds typed fields and bounded validation without rejecting older Dream payloads. ### Key Considerations * Session 07 depends on these Dream health fields for dashboard empty states and generation recovery copy. * Session 05 will reuse the same platform helpers for request-time bridge CLI resolution, so aggregate-only changes should not create a second candidate-resolution system. * The current security posture has no open findings; this session must preserve browser-safe generated data and script-only credential boundaries. ### Potential Challenges * Windows `.lnk` metadata may not be readable in the local test environment: use path/existence heuristics and faithful fixtures for the aggregate detection branch, and treat unreadable shortcut metadata as a degraded detection. * Dream health can be confused with Dream material readiness: health should summarize latest Dream output and lifecycle state for the UI, while material readiness remains the input-quality signal for running Dream. * Aggregate output privacy can regress through new Windows paths: add tests at both sanitizer and write-boundary levels. ### Relevant Considerations * \[P00] **Stack conventions**: Use Bun, TypeScript, Vitest, and existing script module structure. * \[P01] **Old `claude-os-*` naming**: Preserve compatibility aliases where existing Dream paths need them, but do not add new global `claude-os` storage prefixes. * \[P11] **Scheduler state/log privacy boundary**: Dream and aggregate statuses may expose only bounded status metadata, not raw logs or paths. * \[P21] **Claude OAuth material stays script-only**: Provider credentials and bearer headers must not enter browser state, generated data, or logs. * \[P24] **Browser-safe export and triage boundaries**: Generated output must not expose local private paths or raw evidence. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Windows filesystem and registry discovery failing hard instead of degrading. * Dream health metadata overclaiming success when output is stale, missing, or the latest lifecycle failed. * New path detection leaking private usernames or duplicate path variants into generated live data. *** ## 9. Testing Strategy ### Unit Tests * Add `scripts/lib/__tests__/dream-health.test.ts` for healthy, never-ran, stale, silent-failure, and sanitized hint mapping. * Extend app/tool detection tests for Windows Start Menu, local app data, Program Files, terminal inference, unavailable locations, and PATH-first behavior. * Extend scanner tests for backslash and drive-letter normalization. * Extend memory scanner tests for Windows Obsidian registry/config fallback. * Extend sanitizer and aggregate write tests for Windows path privacy. * Extend live-data validation tests for additive Dream health fields. ### Integration Tests * Run targeted Vitest coverage for all changed script and live-data validator owners. * Run `bun run typecheck:scripts` and `bun run typecheck`. * Run a real aggregate write and inspect `src/data/live-data.json`. ### Runtime Verification * Run `bun run aggregate`. * Verify `src/data/live-data.json` contains `dream.healthStatus` and `dream.fixHint`. * Verify generated data contains no unredacted Windows/POSIX home paths, emails, bearer tokens, or private command output. ### Edge Cases * No Dream output exists yet. * Dream output exists but is older than the accepted freshness window. * Latest Dream lifecycle failed, timed out, was killed, or entered backoff. * Windows Start Menu or Obsidian registry is absent. * Windows app directories exist but are unreadable. * Path inputs differ only by slash direction or drive-letter casing. * `CLAUDE_OS_ANONYMIZE=0` remains an explicit operator override while default emission stays redacted. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase38-session01-tier-0-parity-fixes`, `phase38-session02-platform-foundation` * Depended by: `phase38-session04-dream-scheduling-and-setup`, `phase38-session07-dream-engine-product-integration` *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase38-session03-aggregate-and-dream-health/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.