release: Code UX 0.9.7

[numnx]

Summary

Promotes the validated dev integration state to main as Code UX 0.9.7.

This patch release advances the published 0.9.6 baseline with versioned persistent skills and relevance-ranked memory context, weighted sprint progress and asynchronous MCP planning, cross-project intervention visibility and worker clarifications, a substantially richer 3D Chat and local speech stack, configurable Google Drive project mounts, redesigned Projects/Settings/Stats experiences, and broad preview, QA, navigation, and orchestration reliability repairs.

Release Snapshot

Item	Details
Version	0.9.7
Release PR	#2957
Base	origin/main at b685b1a4b4a1243b7042f927dda84f5194fc3abd (0.9.6)
Content head	origin/dev at d2c55ef4bb0671cea6858af7aab4cca7a5d9bcb1
Release branch head	e756aa2a68460615c0535982d16575d608af2daa
Included baseline sync	#2851
Scope	751 files changed; 41,656 additions and 4,892 deletions across runtime, dashboard, documentation, and tests
Integration volume	35 post-sync PRs; 105 non-merge commits
Release branch	release/v0.9.7

What’s New

Persistent Skills, Memory, and Base Agents

• Persistent skill storages are now local-only Git repositories with immutable revisions, read-only provider mounts, stable skill documents, and mutation history routed through the managed skill APIs.
• Skill retrieval indexes compact descriptors and heading-aware chunks, combines semantic and lexical ranking, remains useful without embeddings, and shares one relevance-ranked token budget across planning, workers, QA, CI repair, and merge repair.
• The Memory Map has a read-only Skills tier with project/agent filtering, search, graph inspection, counts, and bounded descriptor-only API responses.
• Project Manager continuations are rendered as agent-owned scheduled events rather than user messages, with delivery state, schedule time, next-step context, and a complete linked-skill inventory.
• Built-in Project Manager and Planning Agent instructions now track base revisions. Untouched presets update automatically, while customized presets receive a guarded provider-assisted compatibility update flow that preserves user behavior and custom instructions.

Sprint Planning, Progress, and Scheduling

• Sprint summaries expose live weighted progress from canonical task lifecycle stages and coding tool-call telemetry while retaining raw completed-task counts.
• MCP sprint planning returns immediately, continues in the background, and wakes the originating chat agent with a completion or failure recap.
• After-sprint schedules now trigger only after successful source completion. Unplanned target sprints go through planning before launch, while already planned targets start directly.
• Scheduler wakeups and planning continuations have clearer Project Manager attribution and auditable state in Threads and 3D Chat.

Human Intervention and Worker Clarification

• A cross-project realtime intervention feed now projects actionable notifications into the global navigation, detail overlays, toasts, and polished sprint waiting/failure states.
• Notification routing is project-aware, excludes worker-owned internal attention where appropriate, and closes overlays reliably on direct navigation.
• Assigned workers and worker pools can request clarification through scoped MCP tools before declaring a task blocked.
• Project Managers can answer those durable clarification requests and resume the same coding session, with orchestration-aware dispatch suppression and continuation recovery.

3D Chat and Local Speech

• 3D Chat supports validated per-response emotions and animation cues, idle and return choreography, refined animated tools, and truthful activity states scoped to the Project Manager rather than unrelated workers.
• Catalog-driven create-app quick actions cover web, desktop, game, shop, and portfolio starting points, remain limited to eligible fresh projects at both UI and server boundaries, and use compact responsive action clusters.
• Delegated work now cycles through a larger non-repeating status-copy deck with calmer timing and reduced live-region churn.
• Local speech adds Whisper Base/Tiny transcription plus Kokoro and Piper synthesis, with explicit Local/API routing, model lifecycle controls, progress, deletion, source links, and 3D Chat microphone/voice controls.
• Speech downloads require explicit license acceptance and expose provenance, commercial-use status, hashes, terms, and size; incomplete bundles surface a repair state and built-in entries fail closed when required metadata is absent.
• German output uses a language-first Piper MLS flow with a pinned eSpeak sidecar, verified artifacts, compatible voice selection, and an explicit recommended download action.
• New assistant replies can play once in 3D Chat without replaying loaded history; accessible manual replay is available in chat and invocation transcripts, and synthesized speech strips widgets, metadata-only payloads, and fenced code.

Projects, Settings, Legal, and Integrations

• Projects is redesigned as an accessible, responsive project gallery with clearer selection/status hierarchy, restrained visuals, and preserved setup and action flows.
• Settings now uses grouped navigation, live overview cards, focused inline workspaces, Smart Find, mobile category navigation, and persisted user accent presets.
• Speech and memory model catalogs are searchable and filterable, provide clearer language/install/license/provenance details, and keep development-only flagged surfaces reachable without changing production defaults.
• General settings exposes the Code UX license and a curated open-source software catalog with dependency license information.
• Projects can mount a linked Google Drive directory into Project Manager and worker containers. Access defaults to read-only, can be configured explicitly, and is propagated through direct worker inbox runs and compacted dashboard threads.

Analytics and Dashboard Experience

• Stats now follows the shared v2 page geometry with an unboxed header, compact command rail, flatter composition sheets, aligned provider details, and continuous task/sprint/Git ledger workbenches.
• Composition presents exact token anatomy, provider distribution, purpose/runtime context, and provider activity without nested decorative KPI layers.
• Provider-share donut geometry remains visible for full and near-full distributions in light and dark themes.
• The public Stats documentation source is synchronized with the canonical redesigned behavior so generated docs parity remains deterministic.
• Dark-theme markdown links use accessible semantic colors across thread, invocation, system-message, and cinematic chat surfaces.

Preview Runtime, MCP, and Catalogs

• Preview startup, reconciliation, and global port allocation are serialized; previously healthy previews can recover after exits, startup cleanup blocks conflicting launches, and orphaned starting rows retry safely.
• Preview host headers are normalized to a trusted local upstream boundary, exit code 137 is reported directly, and startup commands support project defaults plus per-container overrides.
• Trusted previews can opt into validated Docker socket access, Docker CLI, and Compose v2 with explicit host-control warnings and project/session-level policy.
• The built-in Playwright MCP integration is restored to the supported npx @playwright/mcp@latest launch shape, including a compatibility migration for untouched saved defaults.
• The vendored models.dev catalog is refreshed for current provider and model metadata.

Fixes

Orchestration and QA Reliability

• Fixed resolved QA handoffs remaining parked in QA_REVIEW_FAILED; addressed tasks now re-enter review without regressing tasks already settled by another operator action.
• Fixed effectively unbounded QA loops by enforcing hard terminal-attempt ceilings, single-use post-cap verification, and immediate stopping when same-session continuations produce no new patch.
• Fixed no-change coding runs being treated as complete without a structured completion outcome; ambiguous results now fail closed to an actionable blocked state.
• Fixed provider diagnostics being derived from benign Codex output by classifying structured errors and stderr separately and forwarding the relevant failure downstream.
• Fixed sprint-completion QA, CI repair, and active human handoffs pausing otherwise recoverable sprint runs before configured retry guardrails were exhausted.

Preview and Container Reliability

• Fixed preview sessions becoming permanently stuck after interrupted startup, runtime restart, missing containers, or overlapping reconciliation cycles.
• Fixed strict preview applications receiving contradictory host/forwarding headers and rejecting the local preview as an untrusted host.
• Fixed Docker-enabled previews lacking the Compose plugin and requiring operators to leave the Browser page to change project/session Docker policy.
• Fixed preview runtime configuration depending on host Git in shipped execution paths.

Navigation and Realtime Recovery

• Fixed chat draft hydration pairing a newly selected project with a thread retained from the previous project.
• Fixed stale realtime cursors surviving server restart, causing repeated snapshot recovery and route-refresh fan-out.
• Fixed out-of-order project/sprint selection responses leaking a previous project’s sprint into the current Tasks or Live scope.

Speech and 3D Chat Reliability

• Fixed local speech output pairing a newly selected model with an incompatible inherited voice; effective settings now fall back to the selected model’s valid default voice.
• Fixed 3D Chat silently swallowing synthesis and browser playback failures; accessible errors now appear beside voice controls.
• Fixed refresh, navigation, and loaded chat history replaying old assistant audio.
• Fixed speech preprocessing reading rich-widget fences, metadata payloads, or code blocks aloud.
• Removed the unreliable Wav2Vec2 local transcription path and migrated removed or unknown local selections to Whisper Base while preserving external API settings.
• Fixed German 3D Chat TTS after cross-scope model changes and restored scoped playback with compatible model/voice resolution.

Dashboard and Accessibility

• Fixed dark markdown links inheriting an unreadable fixed prose color.
• Fixed quick actions crowding the avatar, overflowing narrow layouts, and bypassing fresh-project eligibility for some app templates.
• Fixed Stats provider-share rings disappearing when one provider represented effectively all usage.
• Fixed built-in MCP tool categories sharing one detail-workspace identity, which caused every category to expand when configuring a single category.

Repository Initialization Security

• Hardened initial README.md creation with a fixed contained file URL and no-follow open so a raced symlink cannot redirect repository seeding outside the validated clone target.

Validation

Local validation on release/v0.9.7 passed:

Check	Result
Quality guardrails	Passed; existing advisory inventory only
Security audit	Passed; no known high-severity vulnerabilities
Typecheck and lint	Passed
Backend tests and coverage	414 files; 5,328 passed, 7 skipped; 83.69% lines, 84.01% functions, 72.54% branches, 82.81% statements
Dashboard tests	238 files; 2,135 passed, 2 skipped
Focused Playwright E2E	28 passed across settings, config, navigation, projects, and full sprint orchestration
Production build	Passed
Documentation parity	Passed after synchronizing the canonical and public security guidance
Packed npm install	@codeuxai/codeux@0.9.7 packed, installed in an isolated workspace, and codeux --help passed
Diff validation	git diff --check passed
Publication preflight	npm version 0.9.7 and tag v0.9.7 do not exist

Commands:

pnpm run ci
pnpm run sync:docs-web
pnpm run check:docs-web
pnpm run build
CODE_UX_SKIP_RELEASE_INSTALL_BUILD=1 node scripts/verify-release-install.mjs
git diff --check

GitHub must additionally pass the complete main promotion matrix before merge, including release policy, CodeQL, package smoke, cross-platform orchestration and Playwright coverage, and Linux/macOS/Windows release-candidate packaging.

Risk and Rollback

• Primary risk is concentrated in local speech model/runtime selection, provider-assisted base-agent updates, clarification/intervention execution state, preview Docker host access, Google Drive mounts, and the breadth of dashboard redesigns.
• Model and Drive access remain explicit configuration choices; speech downloads are license-gated and hash-verified, Drive mounts default to read-only, and preview Docker access stays disabled unless deliberately enabled for a trusted repository.
• Rollback before publication: revert this release PR from main and keep the existing v0.9.6 release active.
• Rollback after publication: npm versions are immutable; publish a corrective patch release rather than attempting to republish 0.9.7.

Known Follow-Up

• No known local release blocker remains. The full GitHub main promotion and cross-platform release-candidate matrices are intentionally pending this PR and must pass before merge.

Full Merged PR Patch Log

• #2856 — version persistent skills and optimize memory retrieval
• #2858 — expose weighted sprint progress
• #2849 — refresh the models.dev catalog
• #2859 — clarify Project Manager continuations and linked skills
• #2870 — repair after-sprint scheduling semantics
• #2876 — unblock resolved QA handoffs
• #2882 — redesign the Projects page
• #2883 — restore the Playwright MCP package default
• #2888 — harden preview container startup
• #2889 — make MCP sprint planning asynchronous
• #2891 — recover orphaned preview startups
• #2873 — improve dark chat link contrast
• #2892 — keep orchestration alive through retry guardrails
• #2886 — add catalog-driven 3D Chat quick actions
• #2896 — enable Compose in trusted preview Docker host mode
• #2897 — bound no-progress QA retries
• #2899 — add cross-project human-intervention visibility
• #2900 — add local speech models and 3D Chat voice controls
• #2901 — default local speech input to a runnable model
• #2914 — gate model downloads and phonemize local speech
• #2920 — add the open-source software and license catalog
• #2923 — update compatible base-agent instructions safely
• #2927 — enrich the 3D Chat agent runtime and interactions
• #2930 — add worker-to-Project-Manager clarification workflows
• #2931 — stabilize dashboard navigation and realtime recovery
• #2932 — stabilize dashboard speech input and playback
• #2933 — remove the unreliable Wav2Vec2 speech model
• #2934 — refine Settings model catalogs
• #2935 — add language-first German speech output
• #2941 — scope asynchronous project and sprint selections
• #2947 — add Google Drive project mounts
• #2948 — restore German 3D Chat text to speech
• #2949 — modernize Settings navigation and personalization
• #2951 — polish and contain 3D Chat quick actions
• #2954 — redesign the Stats composition workspace

Release Branch Commit

• df91087dcea539585def7ec04fcf0f4cae89230f — release: Code UX 0.9.7
• 2f73aba7c2851ffc7706d9b6217fba7a290a178c — fix: repair release CI regressions
• e756aa2a68460615c0535982d16575d608af2daa — test: align settings e2e with focused workspaces