type: meta

slug: zync-os-advanced

base_branch: master

gate0_mode: strict

preset: codex

land_mode: merge-to-main


type: goal

text: Plan C: advanced OS features (virtual desktops, workspaces, focus, lock, folders, taskbar/snap/shortcuts, activity center, health, tenant switcher, Module Manager) + white-label shell + portal/staff/admin shells on extracted packages/os-shell. Spec docs/specs/2026-07-11-zync-os-advanced-design.md is source of truth (SHIPPED after 9 codex gpt-5.6-sol/high review rounds).


type: methodology

text: Spec pins contracts; plan doc pins files/waves/acceptance; tasks POINT to spec sections, never restate. Premium-feel physics live ONLY in .claude/skills/zc-ui-ux-designer (SKILL.md + references) — REQUIRED READING for every UI task; §14 amendments (T3) land BEFORE dependent UI waves. Vision judge = codex models, never Claude. TDD per task; verify subagent claims by opening files; T4 audit assigns migration numbers BEFORE wave-2 backend tasks.


type: intent

text: Complete the Zync OS vision (Phases 5-6): power-user depth, tenant white-label identity, and one shell engine reused across app/portal/admin — classic chrome fully retired.


type: direction

verbatim: make sure that all the physics of the premium feel are actually in the specs, since cheaper models cant think like that


verbatim: if it's IN the spec, fully implement; don't ask whether to build spec'd scope


type: gated

category: policy

needs: verify Plan B landed before launch

why: Plan C consumes Plan B seams (shared layout schema in packages/modules, canDiscard guards, SW purge ack, BottomSheet). Pre-flight MUST verify zync-os-mobile merge is ancestor of origin/master; if not landed, abort.

status: OPEN

source: author


type: anchor

what: design doctrine (+ references/desktop.md, references/mobile.md)


type: task

seat: coder

tier: high

desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 1 (packages/os-shell extraction) for the full contract; spec §0 in full. git mv os engine to packages/os-shell + import rewrite + file: dep (depth-independent law, commit 7cd6f); zync-app becomes ShellHost adapter. ZERO behavior change. Acceptance: FULL A+B suites green UNCHANGED + bundle parity ±5%. Commit only: packages/os-shell/**, apps/zync-app host-adapter files, package.json deps.


tier: medium

desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 2 (Layout schema v2) for the full contract; spec §1 in full. EnvelopeV2 (envelope owns v), DesktopDataV2/MobileDataV2 supersets, migrateLayoutEnvelope(raw) → EnvelopeV2 | null, client-side migration on read. Acceptance: migrator unit matrix PASS + route accepts both versions. Commit only: packages/modules/src/shell-layout-schema.ts, apps/zync-api/src/routes/shell-layout.ts (+tests).


tier: low

desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 3 (Skill amendments §14). Amend design-doctrine files per spec §14 list; GATE for all UI waves. Acceptance: amendment sections present (grep per §14 list). Commit only: .claude/skills/zc-ui-ux-designer/SKILL.md, references/desktop.md, references/mobile.md.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 4 (Audit) for the full contract; spec §Current-state anchors + §6/§7. Enumerate job/integration endpoints + query shapes; record security-settings field names; ASSIGN next free migration numbers to T7/T8/T10; verify RATE_LIMITER_AUTH binding. Acceptance: artifact complete, no unresolved unknowns for waves 2-3. Commit only: docs/plans/audit/zync-os-advanced-audit.md.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 5 (tokens). Add --z-lock, --z-window-pinned, wallpaper dim recipe per spec §14. Acceptance: tokens exported. Commit only: packages/ui/src/tokens/index.css.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 6 (Virtual desktops + overview) for the full contract; spec §2 in full. Max 6 desktops; capacity-aware delete/move; overview live-active-only; URL replaceState + cross-desktop popstate; global cap 12 LRU via canDiscard + exhaustion reject. Acceptance: desktop-scoped store matrix + landed WM matrix re-run PASS + overview/switch probes PASS. Commit only: os-shell store files, packages/os-shell/features/virtual-desktops/**.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 7 (shell_workspaces backend) for the full contract; spec §3 backend in full. Exact DDL (migration number from T4 artifact); field-level authz (shared = settings:write only); caps under pg_advisory_xact_lock; version 409; all mutations audited; tenant-guard dual-layer. Acceptance: authz matrix route tests PASS incl. cross-tenant 404, non-admin shared 403, concurrent cap race, 409. Commit only: new migration, apps/zync-api/src/routes/shell-workspaces.ts, packages/db/src/queries/shell-workspaces.ts (+tests).


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 8 (shell_templates backend) for the full contract; spec §11 backend. DDL with composite FK (tenant_id, role_id) → roles(tenant_id, id) + CHECK device_class; GET member-read-own-role / PUT admin-only; zod §1 schema; ≤64KB. Acceptance: route tests PASS incl. cross-tenant role_id rejected by FK. Commit only: new migration, apps/zync-api/src/routes/shell-templates.ts (+tests).


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 9 (Lock/auth backend) for the full contract; spec §5 backend bullets in full. Cross-field refine on EFFECTIVE merged pair (auto_lock_minutes < idle-logout); reauth limiter RATE_LIMITER_AUTH key reauth:<userId> → 429 + Retry-After: 60, fail-closed; has_password on me/session. Acceptance: route tests PASS (validation grid, N+1 → 429 + header, has_password both states). Commit only: apps/zync-api/src/routes/security-settings.ts, apps/zync-api/src/routes/reauth.ts, me/session payload files (+migration if T4 records one).


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 10 (White-label backend) for the full contract; spec §9 in full — versioned-key wallpaper upload state machine verbatim (write → persist → compensate → cleanup; DELETE nulls first). Migration (wallpaper_url, hide_powered_by); GET + PATCH (PATCH excludes wallpaper_url); proxy allowlist regex wallpaper-[a-f0-9]{8}\.(png|jpg|webp); portal bootstrap white_label plan-gated; manifest worker route Host vs custom_domain WHERE ssl_status='active'. Acceptance: route tests PASS (PATCH set, plan gate, magic-byte/5MB rejects, replacement flips URL + old key 404, proxy regex, manifest host-hit/miss/pending-ssl, bootstrap gated null). Commit only: new migration, apps/zync-api/src/routes/settings/white-label.ts, wallpaper routes, proxy, portal bootstrap, manifest route (+tests).


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 11 (Workspaces UI); spec §3 client. Apply via canDiscard, permission-filter, copy-on-apply, caps/409 surfaces. Acceptance: unit matrix + probes + baselines per spec §Verification + a11y rows. Commit only: packages/os-shell/features/workspaces/**.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 12 (Focus mode); spec §4. Principal-keyed sessionStorage record, priority kinds, exact restore. Acceptance: unit matrix + probes per spec §Verification. Commit only: packages/os-shell/features/focus/**.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 13 (Lock screen); spec §5 client. Overlay --z-lock, display:none privacy, typed reauth results incl. oauth_only/rate_limited, 'Sign in again' path. Acceptance: unit matrix + probes + a11y rows. Commit only: packages/os-shell/features/lock/**.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 14 (Activity + health); spec §6 + §7. Query-option factories + ONE useQueries; partitioned ring + purge hooks; health rollup. Acceptance: unit matrix + probes. Commit only: packages/os-shell/features/activity/** (+health subdir per plan).


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 15 (Chrome: taskbar/snap/top/shortcuts); spec §8 chrome bullets. Position/auto-hide RTL-logical; thirds ≥1440 + group resize; always-on-top --z-window-pinned; SHORTCUT_DEFAULTS + conflicts + overlay. Acceptance: unit matrix + probes + baselines. Commit only: packages/os-shell/features/chrome/**.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 16 (Folders); spec §8 folders. FolderRecord, popover/overlay, dissolve-when-empty, keyboard semantics. Acceptance: unit matrix + probes. Commit only: packages/os-shell/features/folders/**.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 17 (Module Manager); spec §8 Module Manager. Toggleable+plan-gated grid, system excluded, disable via canDiscard, dependency warnings. Acceptance: unit matrix + probes. Commit only: packages/os-shell/features/module-manager/**, module_manager osApp binding in zync-app.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 18 (White-label client); spec §9 application bullet. OKLCH accent utility + 4.5:1 contrast guard fallback + admin health warn; wallpaper application (desktop/lock/mobile home); brand-name splash/header/title; settings UI section. Acceptance: contrast-guard unit matrix + branding e2e incl. fallback path. Commit only: branding utils, boot wiring, settings UI section files.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 19 (Tenant switcher); spec §10 state machine in full. 2FA branches inline (reuse login 2FA component); point of no return at 200; awaited SW purge ack (2s timeout + telemetry); clear TanStack + activity ring + focus record; forward-complete after 200. Acceptance: e2e state-machine walk incl. mocked requires_2fa, pre-200 abort, post-200 forward; single-membership hides switcher. Commit only: packages/os-shell/features/tenant-switcher/**, zync-app host wiring.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 20 (Staff templates UI + boot fallback); spec §11 in full. LAZY FALLBACK single model — no row written on fallback render; personal row only from user's own first save; built-in staff constant for roles lacking settings:write; edit-as-role shell mode. Acceptance: acceptance-12 e2e (fallback no-write, first save wins, template edit reaches non-personalized member). Commit only: roles settings files, boot layout resolution files.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 21 (Customer portal shell); spec §12 in full. PortalShell host: stacked all devices, capabilities all-false, features NONE imported, search-only command center, basePath from :tenantSlug, localStorage-only persistence, white-label via bootstrap. Delete classic portal chrome ONLY after acceptance-11 e2e passes. Acceptance: all 7 portal apps reachable + email deep links + portal-session revocation e2e green + bundle assertion (no feature code). Commit only: apps/zync-app/src/portal/**.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 22 (Zync Control Center); spec §13. os-shell adoption in admin: capabilities all-false, features none, lockScreen:false, token overlay (tokens only), SUPER_ADMIN guard untouched, zero tenant-app leakage. Acceptance: admin e2e on SUPER_ADMIN fixture + bundle assertion + distinct-identity baseline. Commit only: apps/zync-admin/**.


desc: Read docs/plans/2026-07-11-zync-os-advanced.md Task 23 (Final gate). Walk spec §Acceptance criteria 1-15 with evidence; vision judge (codex models; distinct-but-same-family for portal/admin); fault-injection list from §Verification; full A+B+C suites green. Commit only: evidence artifacts under docs/plans/audit/.