> 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-session04-dream-scheduling-and-setup/spec.md). # Session Specification **Session ID**: `phase38-session04-dream-scheduling-and-setup` **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.3 and 1.4 scheduling work into AI OS without adopting upstream Dream execution. Sessions 02 and 03 are complete, so shared platform helpers and Dream health metadata are available; the next executable gap is real Windows Dream scheduling plus setup guidance that tells operators when scheduled Dream runs will actually authenticate. The session upgrades `scripts/install-dream-cron.ts` from a macOS-only launchd installer and Linux/Windows hint printer into a platform-aware installer. Windows must register, query, run, and remove a Task Scheduler task through a real or faithful harness, while macOS launchd behavior remains compatible and Linux guidance points at the AI OS Dream runner sequence. The scheduled command must run AI OS Dream paths, not upstream `scripts/run-dream.ts`. The safest execution boundary is a wrapper sequence that refreshes aggregate data first, then runs `scripts/dashboard-dream-run.ts`, because that script executes the AI OS Dream scheduler job and refreshes live data after new Dream output is written. *** ## 2. Objectives 1. Add Windows Task Scheduler install, query, run, and uninstall support for daily Dream scheduling. 2. Route scheduled Dream execution through AI OS runner paths that write private Dream output and refresh browser-safe live data. 3. Preserve macOS launchd install/uninstall behavior and correct Linux cron guidance around aggregate/Dream ordering. 4. Update setup output with Windows install support and readiness-based headless-auth warnings that avoid false positives after valid setup-token or provider readiness. *** ## 3. Prerequisites ### Required Sessions * [x] `phase38-session02-platform-foundation` - Provides shared platform helpers for Windows paths, CLI candidates, app-data roots, and executable names. * [x] `phase38-session03-aggregate-and-dream-health` - Provides Dream health metadata and proves AI OS Dream output can be projected through refreshed live data. ### Required Tools Or Knowledge * Bun 1.3.14, Vitest, and TypeScript script tests. * Current AI OS Dream runners: `scripts/dashboard-dream-run.ts` and `scripts/scheduler-runner.ts --job dream`. * Current scheduler helpers under `scripts/lib/scheduler/`. * Current readiness helpers: `scripts/lib/hermes-provider-readiness.ts`, `scripts/lib/codex-app-server-readiness.ts`, and `scripts/lib/claude-oauth-usage.ts`. * Upstream comparison sources under `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/`. ### Environment Requirements * Repository root is `/home/aiwithapex/projects/aios`. * Native Windows Task Scheduler can be replaced by a faithful command-building and spawn harness when Windows is unavailable. * No secrets, provider tokens, raw scheduler logs, or private paths may be emitted into browser-visible data. *** ## 4. Scope ### In Scope (MVP) * Operators on Windows can run `bun run install-dream` to register or replace an AI OS Dream scheduled task with idempotent install behavior. * Operators on Windows can query, run, and remove the task through installer-supported commands or clear verification copy. * Scheduled Dream runs invoke AI OS runner paths, not upstream `scripts/run-dream.ts`, and produce private Dream output plus refreshed `src/data/live-data.json`. * macOS launchd install/uninstall keeps its current behavior while switching the scheduled command away from raw `claude -p "/dream"`. * Linux fallback guidance uses the same aggregate-before-Dream ordering and AI OS runner command as the scheduled wrapper. * `scripts/setup.ts` auto-installs on macOS and Windows, skips Linux with actionable guidance, and prints readiness-based auth warnings only when configured providers are not ready. * Tests cover Windows quoting, wrapper generation, Task Scheduler argv, uninstall behavior, macOS regression, Linux fallback copy, setup readiness warnings, and scheduler output safety. ### Out Of Scope (Deferred) * Browser Dream engine selector - Reason: owned by Session 07. * New durable Dream engine storage - Reason: owned by Session 07. * Voice broker, Realtime tokens, or Intelligence portal work - Reason: owned by Sessions 08 and 09. * Request-time Hermes/Graphify bridge Host-header hardening - Reason: owned by Session 05. * Replacing AI OS Dream execution modules with upstream `scripts/run-dream.ts` - Reason: explicitly superseded by AI OS Dream runners. *** ## 5. Technical Approach ### Architecture Keep `scripts/install-dream-cron.ts` as the public CLI entry point, but move platform-specific command construction and wrapper rendering into a testable helper under `scripts/lib/scheduler/dream-install.ts`. That helper should own parseable action types, platform flags, safe quoting, Windows wrapper content, Task Scheduler command argv, macOS plist command construction, Linux cron copy, and bounded readiness notices. The scheduled command sequence should be explicit: change directory to the AI OS repo, run `bun run scripts/aggregate.ts`, then run `bun run scripts/dashboard-dream-run.ts`. The first aggregate gives Dream current browser-safe material, and `dashboard-dream-run.ts` executes `scheduler-runner --job dream` and refreshes live data after a new Dream output is written. Use `;` rather than `&&` only where the existing AI OS behavior intentionally lets Dream attempt recovery after a flaky aggregate refresh. For Windows, write a `.cmd` wrapper in the existing private scheduler/Dream state location and register it through PowerShell ScheduledTasks or `schtasks` with deterministic argv. The implementation must support install/replace, query, run, and uninstall, with explicit exit codes and recovery copy for missing PowerShell, missing Bun, missing scheduler support, and failed registration. ### Design Patterns * Script entry point plus testable helper: Keep CLI behavior simple while unit-testing platform-specific command construction. * AI OS runner boundary: Scheduled tasks invoke `dashboard-dream-run.ts` or `scheduler-runner.ts --job dream`, never upstream `scripts/run-dream.ts`. * Idempotent local writes: Reinstall replaces the existing scheduled task and wrapper without duplicate scheduler entries. * Readiness over presence: Auth warnings derive from configured provider readiness and Claude setup-token evidence, not only Hermes installation. * Bounded operator copy: Warnings expose statuses and commands, not credentials, raw logs, private paths, or token-shaped strings. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------- | | `scripts/lib/scheduler/dream-install.ts` | Build platform-specific Dream install commands, wrappers, verification copy, and readiness warnings. | \~260 | | `scripts/lib/__tests__/dream-install.test.ts` | Cover Windows wrapper/Task Scheduler argv, macOS plist command, Linux fallback, quoting, and readiness warning behavior. | \~240 | | `.spec_system/specs/phase38-session04-dream-scheduling-and-setup/implementation-notes.md` | Record implementation evidence, commands, and verification results during the next workflow step. | \~180 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------- | | `scripts/install-dream-cron.ts` | Delegate to the install helper, add Windows install/query/run/uninstall support, and preserve macOS/Linux behavior. | \~180 | | `scripts/setup.ts` | Auto-install on macOS and Windows, update setup copy, and add readiness-based headless-auth guidance. | \~90 | | `scripts/lib/scheduler/operator-status.ts` | Align Dream scheduler setup guidance with Windows/macOS install support and AI OS runner commands. | \~40 | | `scripts/lib/__tests__/scheduler-operator-status.test.ts` | Assert updated Dream scheduler copy stays command-only and browser-safe. | \~40 | | `scripts/README_scripts.md` | Document Windows Task Scheduler support and the AI OS Dream runner command sequence. | \~45 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Windows install registers or replaces a Task Scheduler task that runs the generated `.cmd` wrapper for AI OS Dream scheduling. * [ ] Windows query, run, and uninstall paths execute the real Task Scheduler command path or a faithful harness and report platform-correct recovery copy. * [ ] The scheduled wrapper refreshes aggregate data before Dream and invokes `scripts/dashboard-dream-run.ts` so private Dream output and refreshed live data are produced. * [ ] macOS launchd plist generation, load, unload, and uninstall behavior remain compatible with current AI OS behavior. * [ ] Linux fallback copy emits an installable cron line that uses AI OS aggregate/Dream ordering and does not mention manual Windows setup. * [ ] Setup auth warnings do not appear when Claude setup-token evidence or configured provider readiness proves scheduled Dream can authenticate. ### Testing Requirements * [ ] Unit tests written and passing for Windows wrapper content, Task Scheduler argv, query/run/uninstall commands, macOS plist command, Linux fallback, setup readiness warnings, and scheduler setup copy. * [ ] Targeted tests run with `bun run test -- scripts/lib/__tests__/dream-install.test.ts scripts/lib/__tests__/scheduler-operator-status.test.ts`. * [ ] Existing scheduler runner and Dream execution regressions run where touched with `bun run test -- scripts/lib/__tests__/scheduler-runner.test.ts scripts/lib/__tests__/dream-execution.test.ts`. * [ ] Script typecheck run with `bun run typecheck:scripts`. ### Non-Functional Requirements * [ ] Windows path quoting handles spaces, apostrophes, `.cmd` executables, and repo paths without command injection. * [ ] Installer failures map to actionable messages and non-zero exits without leaving duplicate scheduled tasks. * [ ] Auth guidance exposes provider readiness statuses only and never prints tokens, bearer headers, raw credential files, or private scheduler logs. * [ ] No new dependencies or lockfile changes are introduced. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings, except generated `.cmd` wrapper content intentionally uses CRLF at runtime. * [ ] Code follows project conventions. * [ ] No product-facing UI route changes. *** ## 8. Implementation Notes ### Working Assumptions * Faithful Windows harness tests are acceptable before native Windows verification: the Phase 38 PRD allows Windows-facing work to be exercised on Windows or a faithful harness, and the critical behavior here is deterministic wrapper content, Task Scheduler argv, and spawn result handling. * The scheduled command should use `scripts/dashboard-dream-run.ts` rather than `scripts/scheduler-runner.ts --job dream`: `dashboard-dream-run.ts` already executes the Dream scheduler job and refreshes live data after new Dream output, satisfying the session delivery bar. * Existing inherited names such as `com.claude-os.dream` and `~/.claude-os` can remain compatibility paths in this session: they already exist in `scripts/install-dream-cron.ts`, and replacing storage prefixes is outside Session 04. ### Conflict Resolutions * Upstream schedules `scripts/run-dream.ts`, while AI OS owns Dream execution through `scripts/lib/dream/**`, `scripts/scheduler-runner.ts`, and `scripts/dashboard-dream-run.ts`; this plan ports only scheduler mechanics and rejects upstream runner wiring. * Upstream headless-auth warnings are based mainly on Claude/Hermes assumptions; this plan uses AI OS readiness modules and Claude setup-token evidence so warnings reflect actual configured provider readiness. * Current Linux guidance says Windows is manual-only; this plan removes that stale copy because Windows becomes auto-installable in this session. ### Key Considerations * Session 05 will harden request-time bridge behavior next; this session should not alter Vite local control-plane endpoints. * Session 07 will add durable Dream engine selection; this session must not create competing browser config storage. * The current security posture has no open findings; scheduler output must stay local and browser-safe. ### Potential Challenges * Windows Task Scheduler command quoting is brittle: isolate command construction in a helper and assert exact argv and wrapper content in tests. * A native Windows host may be unavailable: preserve a faithful harness and clearly record whether native verification was skipped. * Auth readiness can drift across Claude CLI, Hermes, Codex, and API-key modes: keep warning logic conservative and bounded, and avoid claiming readiness from raw token values. ### Relevant Considerations * \[P00] **Stack conventions**: Use Bun, TypeScript, Vitest, and existing script/module structure. * \[P01] **Old `claude-os-*` naming**: Preserve existing compatibility paths where required, but do not introduce new unrelated global `claude-os` identifiers. * \[P11] **Scheduler state/log privacy boundary**: Status surfaces may expose only labels, statuses, durations, exit codes, warnings, lock outcomes, and freshness metadata. * \[P21] **Claude OAuth material stays script-only**: Token-bearing fields, bearer headers, and credential-shaped strings must stay out of browser state, logs, generated data, and setup copy. * \[P15] **Full aggregate remains the compatibility command**: Do not repurpose `bun run aggregate`; scheduled Dream should call explicit Dream scheduler paths. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Windows install writes duplicate or broken scheduled tasks instead of replacing them idempotently. * Scheduled Dream appears installed but runs upstream or raw Claude paths that do not refresh AI OS live data. * Readiness copy either misses a real auth failure or leaks credential-shaped/private information. *** ## 9. Testing Strategy ### Unit Tests * Add `scripts/lib/__tests__/dream-install.test.ts` for Windows `.cmd` wrapper content, Task Scheduler install/query/run/uninstall argv, PowerShell escaping, macOS plist command, Linux fallback copy, and readiness warning states. * Extend `scripts/lib/__tests__/scheduler-operator-status.test.ts` for updated Dream scheduler setup copy and browser-safe output. * Extend or rerun scheduler/Dream tests if install code shares scheduler-runner or Dream execution contracts. ### Integration Tests * Run targeted Vitest coverage for Dream install and scheduler status. * Run scheduler runner and Dream execution regression tests if touched. * Run `bun run typecheck:scripts`. ### Runtime Verification * On Windows or a faithful harness, prove install, query, run, and uninstall command paths are invoked with the expected task name and wrapper path. * On macOS-compatible code path, prove plist command generation still targets launchd and no Windows copy appears. * On Linux path, inspect emitted cron guidance for AI OS aggregate/Dream ordering. ### Edge Cases * Repo paths, Bun paths, log paths, and wrapper paths containing spaces or apostrophes. * Missing Bun, missing PowerShell, failed registration, missing scheduled task during uninstall, and query/run failures. * Valid Claude setup-token evidence, ready Hermes/OpenRouter/Codex provider readiness, missing auth, and unavailable provider readiness. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase38-session02-platform-foundation`, `phase38-session03-aggregate-and-dream-health` * Depended by: `phase38-session05-runtime-bridge-hardening`, `phase38-session07-dream-engine-product-integration`, `phase38-session10-hunk-reconciliation-and-release-gate` *** ## 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-session04-dream-scheduling-and-setup/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.